Update manual pages

1 files changed, 20 insertions, 19 deletions

diff --git a/doc/man/indexamajig.1 b/doc/man/indexamajig.1
index dc40a573..9b587a88 100644
--- a/doc/man/indexamajig.1
+++ b/doc/man/indexamajig.1
@@ -26,22 +26,24 @@ For minimal basic use, you need to provide the list of diffraction patterns, the
 
 .IP \fBindexamajig\fR
 .PD
--i mypatterns.lst -j 10 -g mygeometry.geom --indexing=mosflm,dirax --peaks=hdf5 -o test.stream -p mycell.pdb
+-i mypatterns.lst -g mygeometry.geom --indexing=mosflm,dirax --peaks=hdf5 -o test.stream -p mycell.pdb
 
 .PP
 More typical use includes all the above, but might also include extra parameters to modify the behaviour. For example, you'll probably want to
 run more than one indexing job at a time (-j <n>).
 
-See \fBman crystfel_geometry\fR for information about how to create a file describing detector geometry and beam characteristics.
+See \fBman crystfel_geometry\fR for information about how to create a file describing the detector geometry and beam characteristics.
 
 .SH DIFFRACTION PATTERN LIST
 
-Indexamajig requires an input file with a list of diffraction patterns ("events") to process. In its simplest form, this is just a text files containing a list of HDF5 filenames. 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. The geometry file includes a description of the data layout within the HDF5 files. Indexamajig uses this description to make an educated guess at the number of diffraction patterns stored in each file, and tries to process them all.  You can however single out an event contained in the file for processing, by putting a string describing the event after the file name (see below).
+Indexamajig requires an input file with a list of diffraction patterns ("events") to process. In its simplest form, this is just a text files containing a list of HDF5 filenames. 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. The geometry file includes a description of the data layout within the HDF5 files. Indexamajig uses this description to determine the number of diffraction patterns stored in each file, and tries to process them all.  You can also specify explicity which event(s) you would like to process by putting a string describing the event after the file name(s) in this list.
 
 
 .SH PEAK DETECTION
 
-You can control the peak detection on the command line.  Firstly, you can choose the peak detection method using \fB--peaks=\fR\fImethod\fR.  Currently, two values for "method" are available.  \fB--peaks=hdf5\fR will take the peak locations from the HDF5 file.  It expects a two dimensional array, by default at /processing/hitfinder/peakinfo, whose size in the first dimension equals the number of peaks and whose size in the second dimension is three.  The first two columns contain the fast scan and slow scan coordinates, the third contains the intensity.  However, the intensity will be ignored since the pattern will always be re-integrated using the unit cell provided by the indexer on the basis of the peaks.  You can tell indexamajig where to find this table inside each HDF5 file using \fB--hdf5-peaks=\fR\fIpath\fR.
+You can control the peak detection on the command line.  Firstly, you can choose the peak detection method using \fB--peaks=\fR\fImethod\fR.  There are three possibilities for "method" here.  \fB--peaks=hdf5\fR will take the peak locations from the HDF5 file.  It expects a two dimensional array, by default at /processing/hitfinder/peakinfo, whose size in the first dimension equals the number of peaks and whose size in the second dimension is three.  The first two columns contain the fast scan and slow scan coordinates, the third contains the intensity.  However, the intensity will be ignored since the pattern will always be re-integrated using the unit cell provided by the indexer on the basis of the peaks.  You can tell indexamajig where to find this table inside each HDF5 file using \fB--hdf5-peaks=\fR\fIpath\fR.
+
+\fB--peaks=cxi\fR works similarly to this, but expects four separate HDF5 datasets beneath \fIpath\fR, \fBnPeaks\fR, \fBpeakXPosRaw\fR, \fBpeakYPosRaw\fR and \fBpeakTotalIntensity\fR.  See the specification for the CXI file format at http://www.cxidb.org/ for more details.
 
 If you use \fB--peaks=zaef\fR, indexamajig will use a simple gradient search after Zaefferer (2000).  You can control the overall threshold and minimum squared gradient for finding a peak using \fB--threshold\fR and \fB--min-gradient\fR.  The threshold has arbitrary units matching the pixel values in the data, and the minimum gradient has the equivalent squared units.  Peaks will be rejected if the 'foot point' is further away from the 'summit' of the peak by more than the inner integration radius (see below).  They will also be rejected if the peak is closer than twice the inner integration radius from another peak.
 
@@ -230,7 +232,7 @@ Prefix the filenames from the input file with \fIprefix\fR.  If \fB--basename\fR
 .PD 0
 .IP \fB--hdf5-peaks=\fR\fIpath\fR
 .PD
-When using \fB--peaks=hdf5\fR, read the peak locations from a table in the HDF5 file located at \fIpath\fR.
+When using \fB--peaks=hdf5\fR or \fB--peaks=cxi\fR, read the peak positions from location \fIpath\fR.  See \fBPEAK DETECTION\fR above.
 
 .PD 0
 .IP \fB--tolerance=\fR\fItol\fR
@@ -293,7 +295,7 @@ Normally, peaks which contain one or more pixels above max_adu (defined in the d
 .PD 0
 .IP \fB--no-revalidate\fR
 .PD
-When using \fB--peaks=hdf5\fR, the peaks will be put through some of the same checks as if you were using \fB--peaks=zaef\fR.  These checks reject peaks which are too close to panel edges, are saturated (unless you use \fB--use-saturated\fR), have other nearby peaks (closer than twice the inner integration radius, see \fB--int-radius\fR), or have any part in a bad region.  Using this option skips this validation step, and uses the peaks directly.
+When using \fB--peaks=hdf5\fR or \fB--peaks=cxi\fR, the peaks will be put through some of the same checks as if you were using \fB--peaks=zaef\fR.  These checks reject peaks which are too close to panel edges, are saturated (unless you use \fB--use-saturated\fR), have other nearby peaks (closer than twice the inner integration radius, see \fB--int-radius\fR), or have any part in a bad region.  Using this option skips this validation step, and uses the peaks directly.
 
 .PD 0
 .IP \fB--check-hdf5-snr\fR
@@ -339,10 +341,7 @@ You do not have to use all three of these options together.  For example, if the
 
 By default indexamajig processes all diffraction patterns ("events") in each of the data files listed in the input list. It is however, possible, to only process single events in a multi-event file, by adding in the list an event description string after the data filename. The event description always includes a first section with alphanumeric strings separated by forward slashes ("/") and a second section with integer numbers also separated by forward slashes. The two sections are in turn separated by a double forward slash ('//'). Any of the two sections can be empty, but the double forward slash separator must always be present.  Indexamajig matches the strings and the numbers in the event description with the event placeholders ('%') present respectively in the 'data' and 'dim' properties defined in the geometry file, and tries to retrieve the full HDF path to the event data and the the its location in a multi-dimensional data space. Consider the following examples:
 
-Example 1:
-.br
-
-Assuming that the 'data' and 'dim' properties have been defined like this in the geometry file:
+\fBExample 1:\fR The 'data' and 'dim' properties have been defined like this in the geometry file:
 
 .br
 data = /data/%/rawdata
@@ -351,18 +350,15 @@ dim0 = ss
 .br
 dim1 = fs
 
-The following line:
+The event list contains the following line:
 .br
 
 filename.h5  event1//
 .br
 
-Identifies an event in the 2-dimensional data block lying at the /data/event1/rawdata HDF path in the filename.h5 file
+This identifies an event in the 2-dimensional data block located at /data/event1/rawdata in the HDF5 file called filename.h5.
 
-Example 2:
-.br
-
-Assuming that the 'data' and 'dim' properties have been defined like this in the geometry file:
+\fBExample 2:\fR The 'data' and 'dim' properties have been defined like this in the geometry file:
 
 .br
 data = /data/rawdata
@@ -373,18 +369,21 @@ dim1 = ss
 .br
 dim2 = fs
 
-The following line:
+The event list contains the following line:
 .br
 
 filename.h5  //3
 .br
 
-Identifies an event in the 3-dimensional data block lying at the /data/rawdata HDF path in the filename.h5 file, specifically the 2-dimensional data slice defined by the value 3 of the first axis of the data space.
+This identifies an event in the 3-dimensional data block located at /data/rawdata in the HDF5 file called filename.h5, specifically the 2-dimensional data slice defined by the value 3 of the first axis of the data space.
 
 Indexamajig tries to match the alphanumerical strings to the placeholders in the 'dim' property defined in the geometry file. The first string is matched to the first placeholder, the second to
 the second placeholder, and so on. A similar strategy is followed to match integer numbers to the placeholders in the 'dim' property defined in the geometry file.
 For a full explanation of how the internal layout of the data file can be  described in the geometry file, please see \fBman crystfel_geometry\fR.
 
+You can use \fBlist_events\fR to prepare a list of each event in one or more input files.  Note that you only need to do this if you need to perform some sorting or filtering on this list.  If you want to process every event in a file, simply specify the filename in the input file.
+
+
 .SH BUGS
 ReAx indexing is experimental.  It works very nicely for some people, and crashes for others.  In a future version, it will be improved and fully supported.
 
@@ -410,4 +409,6 @@ You should have received a copy of the GNU General Public License along with Cry
 .BR crystfel_geometry (5),
 .BR cell_explorer (1),
 .BR process_hkl (1),
-.BR partialator (1)
+.BR partialator (1),
+.BR list_events (1),
+.BR whirligig (1)