indexmajig - bulk indexing and data reduction program
-----------------------------------------------------

The indexamajig program takes as input a list of diffraction image files,
currently in HDF5 format.  For each image, it attempts to find peaks and then
index the pattern.  If successful, it will measure the intensities of the peaks
at Bragg locations and produce a list in the form "h k l I", with some extra
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, 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.