What do Elves do?

Elves are capable of everything from indexing the first x-ray diffraction image you get from your crystal, to calculating a phased electron-density map of your protein, suitable for viewing in o. They can also use ARP/wARP to build you a model, resolution permitting.

How do they do it?

Elves use mosflm and the ccp4 suite to process x-ray data, the same way a human crystallographer would. They understand English commands, write scripts, examine log files, and then re-write their scripts.

Although mosflm and ccp4 posess all the funtionality needed to completely "solve" an x-ray structure, they do, indirectly support the use of other packages such as shelx and cns, and they can also take advantage of an installed copy of solve, if it is available.

Okay, what can't Elves do?

Elves cannot make a bad dataset good, but they will try.  If your Elves run is taking days or weeks, have a look at the "processing1.log" or "Wedger.log" and "Scaler.log" files to see what they have been complaining about.

Elves will not try to build a molecular structure (using ARP/wARP) if your resolution is worse than 2.3A (see the ARP/wARP manual as to why).

Refmacer Elves can set up refinement of a partially-built pdb against an mtz with protin/refmac/arp, but they do not run the scripts they write.

Elves do not control the beamline/x-ray setup you are collecting data with (but they will suggest a collection strategy)

What file formats do Elves need?

Elves use mosflm to index and integrate diffraction images, so all the image formats supported by mosflm are, therefore, "supported" by Elves. However, Elves only know how to read the headers of R-axis, MAR, SBC1, and ADSC detectors. So, if you use another detector, you might have to inform Elves of your camera parameters explicitly.

For measured data, Elves usually stick to the CCP4 native mtz file format, but they will also produce copies of output data for shelx, solve, and cns.

Elves also favor CCP4 map files, but, provided mapman or brix are available, they will also produce maps in o format. Support for XtalView will be coming soon.

For atomic coordinates, Elves prefer the Brookhaven PDB file format, but can read heavy-atom sites from a wide variety of formats, including solve's solve.status file, shelx's *.res file, or plain text files with fractional coordinates in them.

Will Elves work on my system?

I have tested Elves on Irix, linux, and OSF1 (DEC unix), and they run fine.

Elves is a csh shell program, so it should, conceivably, work on any Unix platform. The only third-party software requirements are mosflm and ccp4, which they can help you download and install if you don't already have them. Elves also need a few all-but-ubiquitous unix programs like csh, nawk, grep, etc. They can take advantage of denzo, shelx, solve, and wARP, but they can get by without them.

How do I install Elves?

You don't have to.

The Elves program is just a shell script. It needs no "home directory", no environment variables, no configuration, and no compilers. Just do this:

1. get the Elves file.
2. Save it somewhere on your unix file system
3. Make it executable (chmod u+x Elves)
4. Run it with a sentence about what you want Elves to do on the command-line:

unix% Elves process the data in /data/frames

For slightly more detailed installation instructions see the Install page.

How much does Elves cost?

Elves work for free.

(And, when I say "free" I mean within the bounds of the University of California copyright.)

I work for a company that does not qualify as a not-for-profit institution. Can I still get Elves?

Yes, but you'll need to get a commercial license.

Please direct all licensing inquiries to:

Veronica Lanier

Office of Technology Licensing
2150 Shattuck Avenue, Suite 510
Berkeley, CA 94720-1620
(510)-643-7201 FAX: (510)-642-4566

Where do I get Elves?

Right here.

How do I use Elves?

First, get the Elves script to a unix computer. SGI, linux, Digital unix, doesn't matter, the script should run on all unix platforms.

Then, have a look at this short tutorial, or, perhaps, an Example Elves Session, to get an idea as to how you should run Elves, and what they are capable of doing.

For a more detailed explanation, please see the Elves Manual.

How do I tell Elves to do "x"?

Whatever "x" is, type it on the Elves command line, or on one of the internal Elves prompts. Like this:

unix% Elves I want you to "x"
or...
Everything look okay? [Yes]
-> No, actually, I want you to "x"

If the Elves don't understand "x", then I'd like to hear about it. But, in the meantime, try another way of saying "x".

Why mosflm, and not denzo?

This question tends to generate more heat than light, so I will be brief:

There are two reasons why Elves do not (directly) support denzo.

1. denzo is not free, and Elves wouldn't be free either if they required denzo.
2. my personal experiments with denzo and mosflm imply that the performance of both programs is limited by data quality and not algorithms.


Support for denzo may become available in Elves 2.x or later. At present, HKL2000 is the most highly-automated data-processing interface available from HKL Inc.

I already indexed in denzo, can I still use Elves?

Yes.

Just about any stage of data processing can be migrated from denzo into Elves. If you indexed your first frame in denzo, simply provide the resulting output file (usually *.x) to Wedger Elves. If you already integrated all your frames in a denzo batch_job run, you can give all the output *.x files to Scaler Elves. If you have already reduced all your data in scalepack, then you can convert the scalepack files to a multi-column mtz for Phaser Elves. Spotter Elves can also make their spot movies from a scalepack log as well as a scala log.

Can Elves do Molecular Replacement?

Yes.

They use EPMR.

Just run Elves like this:

unix% Elves ~/pdb/searchmodel.pdb ~/pdb/anothermodel.pdb /data/whatever/images/

and, after processing the image data, Elves will run epmr in every possible space group using each search model you list on the command line.

Wedger Elves is in an infinite loop, right?

No. This is normal.

Something I discovered while developing Elves was that re-running many programs with the average of the refined output parameters from a previous run results in noticably improved statistics and better data quality. The stats continue to improve with additional re-refinements. For example, take the average value of the refined unit cell, mosaic spread, distance, beam center, etc. from a mosflm log file. If these numbers differ significantly from the ones you put into the mosflm input file, then one might expect that the refined numbers would have been a better choice for the input file. Turns out they usually are. Even if there is no improvement in your results, you might as well copy the refined numbers back into the script for posterity.

This policy of re-running jobs to improve data quality is the default in Elves. Wedger usually converges its mosflm jobs after four or five iterations, but sometimes a dozen or more are needed. If you are in a hurry, and don't care so much about optimizing your results, just use the word "hurry" on the Wedger Elves command line or at the "W. Elves" prompt.

However, if the loop really does go on for dozens of mosflm runs, it usually means that something else is wrong. Usually it is the space group choice. Imposing symmetry that is not actually there will make it impossible to obtain a stable distance, etc. as the camera parameters try to turn a 91-degree angle into 90 degrees. It never hurts to try temporarily dropping your symmetry to P1 and see what happens to your cell angles.

I think I have anisotropic mosaicity, how do I make Elves aware of this?

The latest version of mosflm will take care of this automatically.  But, if you have an old version...

Use the mosflm keyword "POSTREF USEBEAM". This will cause mosflm to use the refined values of the beam parameters (including mosaicity) instead of the input values (from your script) when measuring spots. Because this command introduces a lot more degrees of freedom into your integration run, it can be unstable. So, you will probably only want to introduce it once all the other refinable parameters have stabilized. By default, Wedger Elves do not use this option.

You can enter this keyword either by typing "POSTREF USEBEAM" on the Wedger Elves internal "W. Elves ->" prompt, or adding a "POSTREF USEBEAM" line to your mosflm.com script.

When I try to kill Elves with <Ctrl>-C, they just sit there. How do I get out?

If you hit <Enter>, you'll get your prompt back. When you hit <Ctrl>-C, Elves die. However, your unix shell may not give you your command prompt back right away, even though the Elves process is long gone. In a few cases, Elves will catch a <Ctrl>-C if they are doing something you might want to interrupt without killing the whole job (calculating a collection strategy, for example). However, these only catch one <Ctrl>-C, so hitting <Ctrl>-C twice will ALWAYS kill the Elves job.

To make sure you kill Elves, hit:

<Ctrl>-C <Ctrl>-C <Enter>

That is, hold down the "Ctrl" key, and press "C" twice. Then press the "Enter" key.

How do I stop Elves from spending so much time looking for "x"?

It's true that Elves can spend quite a long time hunting around your filesystem for programs or data that they need, and this can get annoying. The best way around these searches is, of course, to simply tell the Elves where these files are in the first place (on their command line). It is suprising how many users didn't think of doing that.

However, if you happen to know that the program the Elves are looking for just isn't there, it can be hard to convince them not to look for it. You can try putting something like "no shelx" or "no mapman" on the command line, that usually works. I am working on extending the Elves vocabulary in this department, but, for now, the simplest way around these searches is to just hit <Ctrl>-C during the search, and Elves will usually skip over it. If the Elves job is backgrounded, you can still send them a "<Ctrl>-C" by using:

kill -INT %1

where %1 is the job ID or process ID number of the Elves job you just launched.

Put the word "hurry" on their command line. This usually does the trick. When Elves see this word, they will skip many optimization procedures, and relax the convergence requirement of refined parameters. However, when you have time, you should run them without a "hurry" command, to make sure all your crystallographic parameters have been refined to convergence.

Why do Elves keep saying I have an Osmium or Holmium derivative?

It turns out that Holmium has the closest absorption edge to 1.54A CuK_a emission found on most in-house rotating-anode generators. Osmium has the closest edge to 1.000A. As a rule, Elves try to pick smart defaults, given the kind of data you have. If you don't tell them anything about bound metals, they will try to guess what kind of metal you have from the x-ray wavelength you used for data collection. That is, they assume you would want to collect anomalous data from your bound metal. So, if you have CuK_a data (and you never said anything about what kind of metal you have) Elves will guess Holmium from the information they have.

If you don't have any metals bound in your crystal, then it doesn't matter which one the Elves pick. They only use the metal name to set things up for heavy-atom finding and phasing programs like solve and shelx and, if you don't have metals, you won't be using these programs anyway.

I think I have found a bug in Elves, how do I get rid of it?

The first thing you should do is email James Holton immediately. It's possible I may already have fixed the problem, and, if so, I'll send you a repaired version of Elves.

Additional things you can do to help me out are listed on the Reporting Bugs page.

I thought I found a bug in Elves, but I was wrong...

No, you weren't wrong! Any moment of confusion using Elves represents a failure of the Elves interface to communicate with you, and that's a bug. If this ever happens to you, email James Holton immediately. If you are so inclined, see the Reporting Bugs page for additional information you might want to include in your email.

I don't care if you eventually find your way around the problem, or even if you feel like it was your own mistake. Tell me what happened. Elves are (hopefully) helping you get your research done, so please help me with my research on the best way to design a scientific computer interface. That's the deal, okay? :)

I don't have time to look for bugs in Elves, what can I do to avoid them?

1. Always use simple, declarative sentences when communicating with Elves, its easier for them to understand them.
2. In Wedger Elves, use a text file of mosflm keywords instead of a command-line sentence to communicate things to them. Wedger does not currently accept many crystallographic parameters on its command line.
3. Don't be afraid to kill Elves, edit their output script, and re-run them with the script as an argument. This is the easiest way to customize Elves.
4. Try using the stage-specific scripts in ./Elfsheim/ when you have a particular task in mind.
5. Try to follow the same kind of procedure in the Example Elves Session.
6. If all else fails, read the Manual.

I want to write a program that controls Elves, is there an API?

The best way to control Elves "offline" is to have your control program write a text file containing an English, or "keyword-value" description of what you want Elves to do, and then launch Elves with that file as a command-line argument.

Depending on how much detail and control you need, you might need to run the Elves sub-programs explicitly. For example, if you have a particular beam-stop shadow definition in mind for mosflm, you will have to communicate that directly to Wedger Elves, because the main Elves program does not (at the moment) pass mosflm keywords from its inputs down to the Wedger runs.

For further information about integrating Elves into your own automation system, please contact James Holton.