indexamajig: Rename --min-gradient to --min-squared-gradient

The eventual aim of this is to deprecate the "--min-gradient" option,
resolving the long-standing confusion about whether this option is the
gradient or the squared gradient.

5 files changed, 22 insertions, 13 deletions

diff --git a/doc/man/indexamajig.1 b/doc/man/indexamajig.1
index 1ab4a06d..4b428475 100644
--- a/doc/man/indexamajig.1
+++ b/doc/man/indexamajig.1
@@ -47,7 +47,7 @@ You can control the peak detection on the command line.  Firstly, you can choose
 
 CrystFEL considers all peak locations to be distances from the corner of the detector panel, in pixel units, consistent with its description of detector geometry (see 'man crystfel_geometry').  The software which generates the HDF5 or CXI files, including Cheetah, may instead consider the peak locations to be pixel indices in the data array.  Therefore, the peak coordinates from \fB--peaks=cxi\fR or \fB--peaks=hdf5\fR will by default have 0.5 added to them.  Use \fB--no-half-pixel-shift\fR if this isn't what you want.
 
-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.
+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-squared-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.
 
 If you instead use \fB--peaks=peakfinder8\fR, indexamajig will use the "peakfinder8" peak finding algorithm describerd in Barty et al. (2014). Pixels above a radius-dependent intensity threshold are considered as candidate peaks (although the user sets an absolute minimum threshold for candidate peaks). Peaks are then only accepted if their signal to noise level over the local background is sufficiently high. Peaks can include multiple pixels and the user can reject a peak if it includes too many or too few. The distance of a peak from the center of the detector can also be used as a filtering criterion. Note that the peakfinder8 will not report more than 2048 peaks for each panel: any additional peak is ignored.
 
@@ -258,9 +258,9 @@ Apply a noise filter to the image with checks 3x3 squares of pixels and sets all
 Set the overall threshold for peak detection using \fB--peaks=zaef\fR or \fB--peaks=peakfinder8\fR to \fIthres\fR, which has the same units as the detector data.  The default is \fB--threshold=800\fR.
 
 .PD 0
-.IP \fB--min-gradient=\fR\fIgrad\fR
+.IP \fB--min-squared-gradient=\fR\fIgrad\fR
 .PD
-Set the square of the gradient threshold for peak detection using \fB--peaks=zaef\fR to \fIgrad\fR, which has units of "squared detector units per pixel".  The default is \fB--min-gradient=100000\fR.  The reason it's 'gradient squared' instead of just 'gradient' is historical.
+Set the square of the gradient threshold for peak detection using \fB--peaks=zaef\fR to \fIgrad\fR, which has units of "squared detector units per pixel".  The default is \fB--min-squared-gradient=100000\fR.  \fB--min-sq-gradient\fR and \fB--min-gradient\fR are synonyms for this option, however the latter should not be used to avoid confusion.
 
 .PD 0
 .IP \fB--min-snr=\fR\fIsnr\fR
diff --git a/libcrystfel/src/peaks.c b/libcrystfel/src/peaks.c
index 3d7e8189..49e09868 100644
--- a/libcrystfel/src/peaks.c
+++ b/libcrystfel/src/peaks.c
@@ -345,7 +345,7 @@ static int integrate_peak(struct image *image,
 
 
 static void search_peaks_in_panel(struct image *image, float threshold,
-                                  float min_gradient, float min_snr, int pn,
+                                  float min_sq_gradient, float min_snr, int pn,
                                   double ir_inn, double ir_mid, double ir_out,
                                   int use_saturated)
 {
@@ -402,10 +402,10 @@ static void search_peaks_in_panel(struct image *image, float threshold,
 		dxs = ((dx1*dx1) + (dx2*dx2)) / 2;
 		dys = ((dy1*dy1) + (dy2*dy2)) / 2;
 
-		/* Calculate overall gradient */
+		/* Calculate overall (squared) gradient */
 		grad = dxs + dys;
 
-		if ( grad < min_gradient ) continue;
+		if ( grad < min_sq_gradient ) continue;
 
 		mask_fs = fs;
 		mask_ss = ss;
@@ -525,7 +525,7 @@ static void search_peaks_in_panel(struct image *image, float threshold,
 }
 
 
-void search_peaks(struct image *image, float threshold, float min_gradient,
+void search_peaks(struct image *image, float threshold, float min_sq_gradient,
                   float min_snr, double ir_inn, double ir_mid,
                   double ir_out, int use_saturated)
 {
@@ -542,7 +542,7 @@ void search_peaks(struct image *image, float threshold, float min_gradient,
 
 		if ( image->det->panels[i].no_index ) continue;
 
-		search_peaks_in_panel(image, threshold, min_gradient,
+		search_peaks_in_panel(image, threshold, min_sq_gradient,
 		                      min_snr, i, ir_inn, ir_mid, ir_out,
 		                      use_saturated);
 
diff --git a/src/indexamajig.c b/src/indexamajig.c
index f452b033..2d584726 100644
--- a/src/indexamajig.c
+++ b/src/indexamajig.c
@@ -98,7 +98,8 @@ static void show_help(const char *s)
 "     --filter-noise        Apply noise filter to image data\n"
 "     --threshold=<n>       Threshold for peak detection\n"
 "                            (zaef,peakfinder8 only) Default: 800\n"
-"     --min-gradient=<n>    Minimum squared gradient\n"
+"     --min-squared-gradient=<n>\n"
+"                           Minimum squared gradient\n"
 "                            (zaef only) Default: 100,000\n"
 "     --min-snr=<n>         Minimum signal/noise ratio for peaks\n"
 "                            (zaef,peakfinder8, peakfinder9 only) Default: 5\n"
@@ -350,7 +351,7 @@ int main(int argc, char *argv[])
 	iargs.tols[2] = 5.0;
 	iargs.tols[3] = 1.5;
 	iargs.threshold = 800.0;
-	iargs.min_gradient = 100000.0;
+	iargs.min_sq_gradient = 100000.0;
 	iargs.min_snr = 5.0;
 	iargs.min_pix_count = 2;
 	iargs.max_pix_count = 200;
@@ -531,6 +532,8 @@ int main(int argc, char *argv[])
 		{"xgandalf-max-lvl",                         1, NULL, 356},
 	        {"spectrum-file",                            1, NULL, 357},
 		{"wait-for-file",            1, NULL,        358},
+		{"min-squared-gradient",1,NULL,              359},
+		{"min-sq-gradient",    1, NULL,              359}, /* compat */
 
 		{0, 0, NULL, 0}
 	};
@@ -602,7 +605,9 @@ int main(int argc, char *argv[])
 			return 1;
 
 			case 304 :
-			iargs.min_gradient = strtof(optarg, NULL);
+			iargs.min_sq_gradient = strtof(optarg, NULL);
+			ERROR("Recommend using --min-squared-gradient instead "
+			      "of --min-gradient.\n");
 			break;
 
 			case 305 :
@@ -933,6 +938,10 @@ int main(int argc, char *argv[])
 			}
 			break;
 
+			case 359 :
+			iargs.min_sq_gradient = strtof(optarg, NULL);
+			break;
+
 			case 0 :
 			break;
 
diff --git a/src/process_image.c b/src/process_image.c
index 31abcb21..a5418486 100644
--- a/src/process_image.c
+++ b/src/process_image.c
@@ -266,7 +266,7 @@ void process_image(const struct index_args *iargs, struct pattern_args *pargs,
 		case PEAK_ZAEF:
 		set_last_task(last_task, "peaksearch:zaef");
 		search_peaks(&image, iargs->threshold,
-		             iargs->min_gradient, iargs->min_snr,
+		             iargs->min_sq_gradient, iargs->min_snr,
 		             iargs->pk_inn, iargs->pk_mid, iargs->pk_out,
 		             iargs->use_saturated);
 		break;
diff --git a/src/process_image.h b/src/process_image.h
index 90925592..2a43d11d 100644
--- a/src/process_image.h
+++ b/src/process_image.h
@@ -63,7 +63,7 @@ struct index_args
 	int median_filter;
 	int satcorr;
 	float threshold;
-	float min_gradient;
+	float min_sq_gradient;
 	float min_snr;
 	int check_hdf5_snr;
 	struct detector *det;