1 files changed, 80 insertions, 0 deletions
diff --git a/doc/indexamajig.txt b/doc/indexamajig.txt
new file mode 100644
index 00000000..42f63771
--- /dev/null
+++ b/doc/indexamajig.txt
@@ -0,0 +1,80 @@
+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.