get another manpage




NAME

       X-GEN - xgenstart.py


SYNOPSIS

       xgenstart.py [--help] [--version] [-nsuv] [-fhilmpswxy<val>] [datadir]


DESCRIPTION

       "xgenstart.py" is a Python script that allows you to analyze a few spe-
       cific images, typically test images collected prior to the beginning of
       real  data  collection, in order to obtain an indexing and a refinement
       of the crystal and detector parameters and to use  that  refinement  to
       calculate a data collection strategy. It assumes that the user has col-
       lected a few single images separated fairly widely in  scanning  angle,
       and  that  the  scanning  angle values associated with those images are
       identifiable  from  the  image  headers.  Thus  if   image   blah.0000,
       blah.0090,  blah.0180,  and  blah.0270 were collected at scanning angle
       values of 0, 90, 180, and 270 degrees respectively,  then  xgenstart.py
       will  usually  be  able to determine the unit cell and therefore a data
       collection strategy from those four images.

       xgenstart.py is based on the formalisms used  for  the  general-purpose
       Python script for X-GEN data processing, i.e. xgenproc.py. It omits the
       integration, data reduction, and scaling steps, and replaces them  with
       the  strategy  determination.  It is also set up to expect a few single
       images (like the examples mentioned above) rather than a contiguous set
       of  images,  as is more typicaly in full data collection as implemented
       with xgenproc.py.

       The `xgenstart.py' script is found in the executables directory  within
       which  the  rest  of  the X-GEN executables live. On most machines that
       directory will either be /usr/bin itself, or it will be /opt/xgen/exec,
       or  /home/[INSTALLER]/xgen/exec,  where  [INSTALLER] is the username of
       the person  who  installed  X-GEN  on  your  system.  The  executables,
       libraries,  and resource files for X-GEN, along with the script itself,
       are available for download from http://xgen.iit.edu. Of course, to  run
       this,  you  will  also  need  Python.  This script has been tested with
       Python 2.3.5, and it probably runs on later versions; it may be compat-
       ible with earlier versions too.

       If  you  have collected data into a known directory, you should be able
       to use this script in a simple manner. First, set your  working  direc-
       tory to the directory where the data are, e.g.

              cd /u1/ID7/03_18_05_uXX/Fred/uglyxtal

       Then  if  the  data  are from the SER-CAT ID line and were collected in
       omega, you can process the data by typing "xgenstart.py -s". The script
       will  work properly with data from most other sites (including the SER-
       CAT ID collected in phi) if you simply type "xgenstart.py". The various
       run-time  parameters will enable you to tailor your run of xgenstart.py
       to the specific circumstances under which you're running it.

       Potentially asked questions:

       + How do I know if it has worked?

       The processing results will be written to a subdirectory of  your  cur-
       rent  directory  called xgen. If that directory already exists (because
       you or someone else has already processed these  data  before,  or  has
       processed  a  different dataset in the same directory), then they'll be
       written to the directory xgena. If xgena exists, they'll be written  to
       xgenb, and so on up through xgenz.

       So  if  the output to your screen looks reasonable (the refinement sta-
       tistics that you see near the bottom, just before the strategy calcula-
       tion,  are good), then the processing probably worked. If you cd to the
       processing directory (xgen, or xgena, or whatever), then if you look at
       the  logfile, you can see how effective the processing was. The logfile
       has a name that ends in .xlg.:

              % cd xgena
              % vi *.xlg

       Examine that .xlg file to see the quality of the data. The crystal  and
       detector parameter refinement steps will be nearly at the bottom.

       + What if that doesn't work?

       There are several possible reasons it might not work.

       *      The  software may have failed to find the detector images in the
              current directory. If that happens, you may want to specify your
              image    prefixes    explicitly.    Thus   if   your   data   in
              /u1/ID7/03-18_05/UXX/Fred/uglyxtal/ have filenames  ugly01.0001,
              ugly01.0002, . . . , up through ugly01.0137, then you might want
              to try

              % xgenstart.py -s -pugly01

              If it's still unable to find the images, you may need additional
              help from the author (howard@iit.edu).

       *      It  may fail during auto-indexing.  There are some special cases
              for this problem:</li>

              - It may have gotten the stepsize wrong.

              Note the rules I've given above. If you collect on the  bending-
              magnet  beamline,  or if you collect on the ID line using phi as
              your data collection motor, then you don't need to flip the sign
              of  the  stepsize.  If you collect on the ID line using omega as
              your data collection motor, then you need to specify  the  sign-
              flip:

              % xgenstart.py -s

              -  It  may  not have found enough reasonable centroids to refine
              on.

              -  The crystal may be twinned or pathological in some other way.

              In this  case  you  may  need  to  abandon  the  non-interactive
              approach to using X-GEN and learn how to use the specific appli-
              cations within it. Check out the actual  documentation  for  the
              individual X-GEN executables at http://xgen.iit.edu.

       *      It  may auto-index correctly, but it may not account for all the
              Laue Laue symmetry correctly. If you actually  know  the  space-
              group,  you can specify it at xgenstart.py runtime by its Inter-
              national Tables number.  Thus if your crystal is  in  spacegroup
              P6(2)22 (International Tables # 180), you can specify it at run-
              time as:

              % xgenstart.py -i180

              You can combine this flag with the others listed above if appro-
              priate.

       + Does "xgenstart.py" have run-time options?

              Yes. They're listed under "Options".

       + I want to see the images!

              You  can  readily  do  so.  Change  directory to your processing
              directory, establish your environment variables, and examine the
              images with "pdisplay":

              % cd xgen      # cd to processing directory
              % source *.com # establish environment variables
              % pdisplay     # examine your images

              "pdisplay" has many options that you can explore.

       + I'm stuck in ways that aren't discussed here. What do I do?

              Read  the  full documentation for X-GEN, or call or e-mail Andy:
              773-368-5067 (cell), 312-567-5881 (IIT), or howard@iit.edu.


OPTIONS

       --help Print this message.

       --version
              Print a header indicating the version of X-GEN that is  running.

       -n     ordinarily  the refinement portion of X-GEN does a simple-minded
              recentering of the main beam  immediately  after  auto-indexing.
              This option directs the package NOT to do that.

       -s     Flip  the  sign of the rotation stepsize from the value that the
              program intuits. We try to stay in synch with the stepsize  con-
              ventions  for  every  goniostat,  but  if  we get it wrong, this
              allows recovery.

       -u     Same as --help, i.e. print this message.

       -v     Same as --version, i.e. print the X-GEN version number and  then
              exit.

       -h<val>
              Specify the last image we will process.

       -i<val>
              Specify  an  International  Tables  spacegroup number.  If auto-
              indexing succeeds, and the Laue group associated with the speci-
              fied  spacegroup  number is a plausible solution to the Bravais-
              lattice calculation, then we will impose this spacegroup  number
              during processing. To specify a rhombohedral indexing of a rhom-
              bohedral unit cell, add 100 to the spacegroup; thus R32  indexed
              rhombohedrally is -i255.

       -l<val>
              Specify  the  first  image  we  will process. If images 1-13 are
              garbage, we can specify -l14.

       -m<val>
              Search for spot centroids out of  <val>  different  sub-runs  of
              "spots". If <val> is 4, for example, and there are 120 images in
              the FRAMES index, then we will extract spots from images 1,  31,
              61,  and  91.  We'll merge those lists of images together before
              auto-indexing and refinement.  The default for <val> is 4.

       -p<val>
              Process data images whose filename prefix is <val>.   Ordinarily
              "xgenstart" picks the prefix in the data directory for which the
              largest number of images is present; this option  allows  us  to
              specify  exactly  which  prefix to use.  Thus if george1a.0001 -
              george1a.0180 and george1b.0137 - george1b.0219 are both present
              in  a  directory,  we  can  tell  "xgenstart"  to  work with the
              george1b data by specifying xgenstart -pgeorge1b

       -w<val>
              In multi-centroid mode (-m<val>), we specify here the number  of
              contiguous  images  in each sub-run that will be examined during
              indexing. Ordinarily the correct value for this will be 1 unless
              the we're doing small-molecule data collection.

       -x<val>
              Specify the main-beam X position IN PIXELS as <val>.

       -y<val>
              Specify  the  main-beam  Y  position  IN PIXELS as <val>.  These
              options must be specified together. If they are, the script will
              run  "calibrate  -j"  with  the  appropriate  beam-center values
              before beginning processing.

       [datadir]
              If a non-flag argument is specified, it is taken to be the  name
              of  the  directory  in which the search for images is to be per-
              formed. By default we specify  the  current  working  directory.

       xgenstart.py -d -pgeorge1a -h180 -x2028 -y2029
              Process the images with

              prefix "george1a", assuming that the last usable image  will  be
              number   180;  assume  that  the  beam  center  is  at  [X,Y]  =
              [2028,2029]; compress the data after integration.


REPORTING BUGS

       Report bugs to Andy Howard at howard@iit.edu or 312-567-5881.


COPYRIGHT

       Copyright (C) 2002, Illinois Institute of  Technology.   See  the  file
       'LICENSE' for information on usage and redistribution of this file, and
       for a DISCLAIMER OF ALL WARRANTIES



Version 5.5.5                    October 2005                         X-GEN(1)

"get my man!" .. in association with man2html and cor