|Copyright||© 2004-2018 by Global Phasing Limited|
|All rights reserved.|
|This software is proprietary to and embodies the confidential technology of Global Phasing Limited (GPhL). Possession, use, duplication or dissemination of the software is authorised only pursuant to a valid written licence from GPhL.|
|Documentation||(2004-2018) Clemens Vonrhein, Claus Flensburg, Wlodek Paciorek & Gérard Bricogne|
process -d 01This assumes that you want to have the processing output in a subdirectory of the directory containing images. Or maybe symbolic links were created to have images visible in the current directory.
Of course, the above command will actually not save standard output. So it would be better to run
process -d 01 > 01.lis 2>&1 # bash/sh/zsh/kash - or - process -d 01 >& 01.lis # tcsh/cshin order to save standard output in a file (here 01.lis). It seems a good idea to name output (sub)directory and file with standard output in a consistent way (and not using "test", "new", "newer" etc).
process -I /some/where/Images -d 01Sometimes it might be useful to use an explicit specification of images to be used - e.g. if a range of images should be excluded or a larger dataset should be split into several parts.
process -Id "early,/some/where/Images,lyso_####.cbf,1,450" -d 01or
process -Id "early,/some/where/Images,lyso_####.cbf,1,450" \ -Id "late,/some/where/Images,lyso_####.cbf,451,900" \ -d 01... which isn't quite a one-liner any more.
If it is known that the beam centre in the image header is completely wrong and the correct value is known (or has been determined e.g. visually), one can give this to the program via the beam parameter:
process beam="1230 1330"-d 01The beam coordinates have to be given in pixels (not mm). If the values in the image header are correct but use a different convention (the imginfo program and beam8.sh jiffy might be helpful here), the BeamCentreFrom parameter wil define the conversion:
process BeamCentreFrom=header:-y,x -d 01If the conversion itself is not know (and one can't determine this conversion visually from the actual diffraction images), then running once with
process BeamCentreFrom=getbeam:init -d 01could be helpful - although it is not guaranteed to find the correct answer in all cases.
process -M LowResOrTricky -d 01The main purpose of the settings within this macro (see process -M show for details) is to switch off parameter refinement during integration - since this can become unstable for problem cases. More cycles of integration and post-refinement are done to compensate for this, resulting in a longer run-time but hopefully better behaved integration. Please be aware that this will most likely cause problems for datasets where radiation damage induced a significant change in cell parameters, because then the assumption of a single set of cell parameters for all images no longer holds.
process -M listwill give a short summary of each macro while
process -M showwill show the actual parameter settings for each macro. Please remember that command-line arguments are processed in the order they are read (and macros are expanded at that point). Settings later on the command-line might therefore overwrite previous settings.
If there is a pre-defined macro for a given beamline, running
process -M SlsPXIII -d 01will pick up those settings. Otherwise please check the autoPROC wiki for known (and hopefully up-to-date) settings of other beamlines.
What should one try if there are problems when running with (most) default settings? There are different stages of the data processing run that we can look at separately below.
imginfo /where/ever/some.imgprints the content of the image header.
The imginfo program within autoPROC is the tool that handles image formats and header content. We try to cater for as many variants of image headers as possible - but will not encode work-arounds for every single detector employed anywhere in the world (unless there is a very good reason for it that we can get convinced of). In most cases where autoPROC/imginfo fails in reading the image header correctly, this is due to very unusual values or items being written into the header by the beamline control software. Unfortunatly, we very rarely get a preview of changed image headers (beamline reconfiguration etc). If every beamline/instrument would post detailed and up-to-date information about the beamline configuration and the meaning of the image header items (sticking a post-it to the hutch door doesn't count), life would be easier for users and software developers by an order of magnitude.
As you can see from the rant above, image headers are a permanent pain for us and users: if you hit problems in that area, please contact us with some example files and (after we analyse what is going on) then get back to the beamline staff to ensure any problems are fixed asap ... so that other users won't hit the same problems as well.
A common difference to the default settings is a change in direction for a positive rotation around the spindle axis. This can be specified using
process ReversePhi=yes ...Another possibility (and sometimes in conjunction with the above) is a difference in beam centre specification. If
imginfo some.cbfshows that the beam-centre is significantly (more than a couple of pixels) off the image centre, then the correct convention should be used with e.g.
process BeamCentreFrom=header:y,x ...How do you find that convention:
process BeamCentreFrom=getbeam:init ...
If data was collected using e.g. the Phi-axis of a multi-axis (Eulerian or Kappa) goniostat, the exact rotation needs to be calculated using the exact specifications of the goniostat. This involves the Kapparot system and the XdsGetRotationAxisViaKapparot parameter.
Of course, indexing might still fail (or give problems) if everything is correctly defined but it is the diffraction pattern that gives problems. By default, autoPROC will already try to optimise the indexing solution via the XdsOptimizeIdxrefAlways parameter. This can still fail and a few possible settings could be:
process autoPROC_XdsKeyword_REFINEIDXREF="BEAM AXIS ORIENTATION CELL" ...This will fix the detector origin position during indexing.
process RunIdxrefStartWithTop=1000 ...
process RunIdxrefExcludeHighRes=3.5 ...
process RunIdxrefExcludeIceRingShells=yes ...
process autoPROC_XdsKeyword_SPOT_RANGE="1 10|101 110" ...
process -M LowResOrTricky ...Sometimes it is better to exclude problematic image ranges right frmo the start, e.g. with
process -Id "early,/where/ever/images,lyso_####.cbf,1,435" ... - or - process -Id "later,/where/ever/images,lyso_####.cbf,101,900" ... - or - process -Id "middle,/where/ever/images,lyso_####.cbf,101,435" ...If a few intermediate images are buggy (issues with beamline or detector hardware/electronics etc), these images could be moved away using
mv lyso_201.cbf lyso_201.cbf.bad mv lyso_202.cbf lyso_202.cbf.bad process -Id "allgood,/where/ever/images,lyso_####.cbf,1,900" ...
The easiest way of improving the scaling results is to include only data from well diffracting image ranges. Running e.g.
aP_scale -mtz XDS_ASCII.mtz \ -P Lyso nat early -b 1-435 -id early_01 > early_01_aP_scale.logor
aP_scale -mtz XDS_ASCII.mtz \ -P Lyso nat later -b 101-900 -id later_01 > later_01_aP_scale.logor
aP_scale -mtz XDS_ASCII.mtz \ -P Lyso nat middle -b 101-435 -id middle_01 > middle_01_aP_scale.logThis will obviously only give a complete dataset if high enough multiplicity was collected (another good argument for low-dose, high-multiplicity data collection strategies).