Update doc/indexamajig

1 files changed, 69 insertions, 72 deletions

diff --git a/doc/indexamajig b/doc/indexamajig
index 7d6e0d16..42f63771 100644
--- a/doc/indexamajig
+++ b/doc/indexamajig
@@ -9,75 +9,72 @@ information about the locations of the peaks.
 
 For minimal basic use, you need to provide the list of diffraction patterns,
 the method which will be used to index (currently there is only one available
-method), a file describing the geometry of the detector, and a PDB file which
-contains the unit cell which will be used for the indexing.
-
-Syntax: src/indexamajig [options]
-
-Process and index FEL diffraction images.
-
-  -h, --help              Display this help message.
-
-  -i, --input=<filename>  Specify file containing list of images to process.
-                           '-' means stdin, which is the default.
-
-      --indexing=<method> Use 'method' for indexing.  Choose from:
-                           none     : no indexing
-                           dirax    : invoke DirAx
-  -g. --geometry=<file>   Get detector geometry from file.
-
-
-With just the above options, this program does not do much of practical use.
-You should also enable some of the following:
-
-      --near-bragg        Output a list of reflection intensities to stdout.
-                           When pixels with fractional indices within 0.1 of
-                           integer values (the Bragg condition) are found,
-                           the integral of pixels within a ten pixel radius
-                           of the nearest-to-Bragg pixel will be reported as
-                           the intensity.  The centroid of the pixels will
-                           be given as the coordinates, as well as the h,k,l
-                           (integer) indices of the reflection.  If a peak
-                           was located by the initial peak search close to
-                           the "near Bragg" location, its coordinates will
-                           be taken as the centre instead.
-      --simulate          Simulate the diffraction pattern using the indexed
-                           unit cell.  The simulated pattern will be saved
-                           as "simulated.h5".  You can TRY to combine this
-                           with "-j <n>" with n greater than 1, but it's
-                           not a good idea.
-      --filter-cm         Perform common-mode noise subtraction on images
-                           before proceeding.  Intensities will be extracted
-                           from the image as it is after this processing.
-      --filter-noise      Apply an aggressive noise filter which sets all
-                           pixels in each 3x3 region to zero if any of them
-                           have negative values.  Intensity measurement will
-                           be performed on the image as it was before this.
-      --write-drx         Write 'xfel.drx' for visualisation of reciprocal
-                           space.  Implied by any indexing method other than
-                           'none'.  Beware: the units in this file are
-                           reciprocal Angstroms.
-      --dump-peaks        Write the results of the peak search to stdout.
-                           The intensities in this list are from the
-                           centroid/integration procedure.
-      --no-match          Don't attempt to match the indexed cell to the
-                           model, just proceed with the one generated by the
-                           auto-indexing procedure.
-      --unpolarized       Don't correct for the polarisation of the X-rays.
-      --check-sanity      Check that indexed locations approximately correspond
-                           with detected peaks.
-
-
-Options for greater performance or verbosity:
-
-      --verbose           Be verbose about indexing.
-      --gpu               Use the GPU to speed up the simulation.
-  -j <n>                  Run <n> analyses in parallel.  Default 1.
-
-
-Control of model and data input:
-
-     --intensities=<file> Specify file containing reflection intensities
-                           to use when simulating.
- -p, --pdb=<file>         PDB file from which to get the unit cell to match.
- -x, --prefix=<p>         Prefix filenames from input file with 'p'.
+method), a file describing the geometry of the detector, a PDB file which
+contains the unit cell which will be used for the indexing, and that you'd like
+the program to output a list of intensities for each successfully indexed
+pattern.  You should redirect the output (stdout, but not stderr) of the program
+to a file for later analysis.  Here is what the minimal use looks like on the
+command line, with each argument shown on a separate line.  In practice, you'd
+put this all on one line:
+
+indexamajig
+-i mypatternlist.lst
+--indexing=dirax
+--geometry mygeometry.geom
+-p mystructure.pdb
+--near-bragg
+> myoutputfile.txt
+
+More typical use includes all the above, but might also include a noise or
+common mode filter (--filter-noise or --filter-cm respectively) if detector
+noise causes problems for the peak detection.  The HDF5 files might be in some
+folder a long way from the current directory, so you might want to specify a
+full pathname to be added in front of each filename.  You'll probably want to
+run more than one indexing job at a time (-j <n>), and you might want to correct
+the intensities of saturated peaks according to a list stored elsewhere in the
+HDF5 file:
+
+indexamajig
+-i mypatternlist.lst
+--indexing=dirax
+--geometry mygeometry.geom
+-p mystructure.pdb
+--near-bragg
+--filter-noise
+--prefix=/some/horribly/long/pathname/ending/in/a/slash/
+-j 16
+--sat-corr
+> myoutputfile.txt
+
+The table of saturation values for --sat-corr should be located in the HDF5 file
+as follows: /processing/hitfinder/peakinfo_saturated.  It should be an n*3 two
+dimensional array, where the first two columns contain x and y coordinates and
+the third contains the value which should belong in a peak at location x,y.  The
+value will be divided by 5 and spread in a small cross centred on that location.
+
+See doc/geometry for information about how to create a geometry description
+file.
+
+
+Unconventional Use
+------------------
+
+There are some less often used options, for example "--dump-peaks" to dump the
+peak locations found by the peak search (in turn presented to the indexer).
+This might be useful if you want to check the performance of the peak finder.
+If you run a large dataset with bot --dump-peaks and --near-bragg enabled,
+you'll generate a large amount of data.  To separate the peaks from the
+indexed peaks, use scripts/stream-split as follows:
+
+scripts/stream-split myoutputfile.txt indexed.txt peaks.txt
+
+.. to generate both indexed.txt and peaks.txt.  One of the last two arguments
+can be "/dev/null" if you're only interested in the other.
+
+
+"Gotchas"
+---------
+
+Don't run more than one indexamajig jobs simultaneously in the same working
+directory - they'll overwrite each other's DirAx files, causing subtle problems
+which can't easily be detected.