Frequently Asked Questions
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
commands, write scripts, examine log files, and then re-write their scripts.
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).
Elves can set up refinement of a partially-built pdb against an mtz
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,
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
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,
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:
get the Elves
Save it somewhere on your unix file system
Make it executable (chmod u+x Elves)
Run it with a sentence about what you want Elves to do on
unix% Elves process the data
For slightly more detailed installation instructions see
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?
Office of Technology
2150 Shattuck Avenue, Suite 510
Berkeley, CA 94720-1620
(510)-643-7201 FAX: (510)-642-4566
Where do I get Elves?
How do I use Elves?
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
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"
Everything look okay? [Yes]
-> No, actually, I want you
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 is not free,
and Elves wouldn't be free either if they required denzo.
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
I already indexed in denzo, can I still
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)
Elves. If you already integrated all your frames
in a denzo batch_job run, you can
give all the output *.x files to
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 can also make their spot movies from a scalepack log as well
as a scala log.
Can Elves do Molecular Replacement?
They use EPMR.
Just run Elves like this:
unix% Elves ~/pdb/searchmodel.pdb
and, after processing the image data, Elves will run epmr
in every possible space group using each search model you list on the command
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
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
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"
kill -INT %1
where %1 is the
job ID or process ID number of the Elves job you just launched.
How do I stop Elves
from spending so much time "optimizing"?
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 CuKa 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 CuKa data (and you never said anything about
what kind of metal you have) Elves will guess Holmium from the information
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
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
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?
Always use simple, declarative sentences when communicating
with Elves, its easier for them to understand them.
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.
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.
Try using the stage-specific scripts in ./Elfsheim/
when you have a particular task in mind.
Try to follow the same kind of procedure in the Example
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
to the Elves Page.
This page is not finished. It will never be finished, and neither will
yours. Admit it.
James Holton <firstname.lastname@example.org>