Content
Introduction
Under some circumstances there might be problems in getting autoPROC to run, complete successfully or giving the expected results. Here, we try to address those issues - if this is incomplete or doesn't cover the problem you are encountering, please contact us at proc-develop@globalphasing.com.
ERROR: licence key file ".licence" not found
An error message during installation with the test
ERROR: licence key file ".licence" not found (please note spelling!)
should be pretty self-explanatory and obvious - but if you are a total beginner in using a terminal/shell, this can be daunting. Furthermore, some operating systems make it a bit difficult to work with those "hidden" files (files starting with a dot). So what can you do?
Since you are already working in a terminal, you can first have a look what is present in the current directory:
ls -l -a
should show you all files (and directories) with details (that's what the "-l" argument does). The "-a" flag ensures that those "hidden" files are also shown. What you should see is something like this:
-rw-r--r--. 1 vonrhein gphl 10156 Jan 11 13:57 .licence
-rw-r--r--. 1 vonrhein gphl 71754752 Jul 26 14:45 GPhL_autoPROC_snapshot_20230726.darwin.tar
-rw-r--r--. 1 vonrhein gphl 32260 Jul 26 14:45 GPhL_autoPROC_snapshot_20230726_install.sh
or (if you are on a Linux system)
-rw-r--r--. 1 vonrhein gphl 10156 Jan 11 13:57 .licence
-rw-r--r--. 1 vonrhein gphl 82647040 Jul 26 14:45 GPhL_autoPROC_snapshot_20230726.linux64.tar
-rw-r--r--. 1 vonrhein gphl 32260 Jul 26 14:45 GPhL_autoPROC_snapshot_20230726_install.sh
Now back to the error message: you are probably missing the .licence file because
- it's not there at all
- in that case you need to go back to your emails and extract it from the separate email you should have received at the same time the email with download instructions arrived)
- it is named something else
- this might be done automatically by your mail system (some don't like attachements where teh filename is given without an extension or with a leading dot)
- you need to rename it using a simple shell command
mv my.licence .licence
- obviously changing the string "my.licence" to the filename you currently have (and that the "ls -l -a" command told you about)
- make sure to follow the correct syntax, i.e. at least one space after "mv" and also between the two filenames (to move the old one to the new one)
- remember that the new file starts with a dot
- it is best to check things again by doing
ls -la
file .licence
We are aware that the above explanation is extremely detailed (for those that have some basic knowledge of shell/terminal) and most likely not detailed enough for everyone else (in that case we recommend some basic tutorials of which there are dozens - you could do worse than searching for e.g. "shell terminal intro 2023 youtube" or such).
See also general information about AutoProcLicensing.
The program doesn't run
To test if the program is correctly installed, run
% process -h
which should return the online help menu. Otherwise:
- if you get an error about licensing:
- remember that every machine you want to run the software on needs to have its own licence key (a line with 6 numbers in the .licence file). This need has been removed for academic releases after March 2015!
- Also, those licence keys have an expiry date, after which you need to renew your licence with us.
- autoPROC uses a variety of external programs and packages and assumes a 'standard' installation of those packages on your computer. If there is extensive use of alias and wrapper systems in your environment, it can cause autoPROC not finding the expected programs.
- XDS: we expect 'xds_par' or 'xds' in your PATH.
- CCP4: the normal setup will have the binaries from $CBIN in your path. See also the $autoPROC_home/machines/*/ccp4.setup file(s) if they exist. The currently latest (and recommend) version is 7.0.057.
- POINTLESS, AIMLESS: those usually come as part of the CCP4 installation (pointless and aimless binary). Pre-release versions are not recommended for production usage of autoPROC.
- gnuplot: this is used to produce several very useful graphs and plots. Those are important to judge data quality and diagnose potential problems with crystal, data collection or hardware. autoPROC provides its own copy of gnuplot (version 4.6 patchlevel 7).
autoPROC doesn't work
The first thing to try: does it work with all defaults, ie.
% process -d 01 > 01.lis 2>&1
- or -
% process -d 01 >& 01.lis
(make sure you don't have a ~/.autoPROC file with some specific settings: this will be read by every run).
A failure often manifests itself earlier on in the processing - so check the messages in standard output (01.lis in the example above) carefully: they try to give useful information.
Indexing is failing or wrong
Please first check the page about beamline-specific settings.
- first suspect: the beam centre is wrong
- check the beam centre in the image header with the imginfo program
- you can set the starting value for the beam centre with
% process beam="1234 5678" ...
- remember that MOSFLM expects the beam centre in mm but XDS expects it in pixels (imginfo gives you both)
- XDS actually expects the so-called detector origin (point on detector closest to origin of coordinate system, ie. intersection of direct beam with rotation axis). This is defined differently from the beam centre (point on detector where the direct beam hits). If the detector normal and the incident beam direction are not parallel, these two values will differ. Usually, the difference is small enough to be ignored, but be careful with very large cell dimensions
- for any given beamline/instrument, the relation between the beam centre values recorded in the header (following one convention) and the convention used by autoPROC, can be determined once and then used throughout - assuming the beam centre value is written correctly into the image header. This is the recommende way!
% process BeamCentreFrom=header:y,x ...
- other possible issues: the distance (mm), wavelength (A) or oscillation range (degree) is wrong in the image header: please check with imginfo. You can set those values e.g. with
% process wave=1.01234 dist=456.78 autoPROC_XdsKeyword_OSCILLATION_RANGE=1.50 ...
See also the page about beamline-settings.
I get the wrong spacegroup
Apart from the more philosophical question, what the 'correct' spacegroup is:
- Please check that the beam-centre is correctly given or identified
- Is the difference only due to missing screw axes (P2 versus P21), the enantiomorph (P41 versus P43) or some axis permutation (e.g. in orthorhombic spacegroups)? Maybe enforcing the 'correct' spacegroup using a reference MTZ file with the -ref flag could help?
The scaling part crashes
Please first check the examples for scaling to see if the simplest scaling might work. It is also possible that some particularly poor data creates problems during scaling: one could try to limit the scaling initially to only a subset of images (known to show good diffraction patterns).
Results are worse than with program X
Not much we can help here - unless we get some details about
- how are they worse?
- does the start of the autoPROC run still looks ok but it performs worse towards the end?
- was X used in fully automatic mode with all defaults or was some fine-tuning of parameters required to get those better results?
- is there a possibility of sharing those datasets for internal development only?
- can you contact us at proc-develop@globalphasing.com?
Debugging processing problems with HDF5 datasets (*_master.h5)
It can be very help compring the information given by
imginfo /where/ever/your_master.h5
with the output of e.g.
h5ls -rdv /where/ever/your_master.h5/entry/instrument
(yes: there is no space after the *.h5 filename). You will need to install hte HDF5 tools on your system though (usually provided by OS packages at least under Linux).
Sometimes running
imginfo -v -v -v /where/ever/your_master.h5
might shed a light on any problems: it will report what data items "imginfo" is looking at (i.e. what it expects), what fallback/alternatives it tries and where it fails.