Improve documentation of -E and -D in blockm* (#8076)

Break the directives up to bulleted sections, and standardize presentation. Also check that blockmode only selects on of +a+l+h.
GenericMappingTools · Nov 26, 2023 · 97eaf73 · 97eaf73
1 parent ec877ba
commit 97eaf73
Show file tree

Hide file tree

Showing 4 changed files with 64 additions and 53 deletions.
diff --git a/doc/rst/source/blockmean.rst b/doc/rst/source/blockmean.rst
@@ -97,7 +97,7 @@ Optional Arguments
     for each block. Output order becomes
     *x*,\ *y*,\ *z*,\ *s*,\ *l*,\ *h*\ [,\ *w*]. Default outputs
     *x*,\ *y*,\ *z*\ [,\ *w*]. See |-W| for enabling *w* output.
-    If **-E+p**\|\ **P** is used then input data uncertainties are expected and *s*
+    If **-E+p**\|\ **P** is used then input data uncertainties are expected and **s**
     becomes the propagated error of the weighted (**+p**) or simple (**+P**) *z* mean.
 
 .. _-G:

diff --git a/doc/rst/source/blockmedian.rst b/doc/rst/source/blockmedian.rst
@@ -92,31 +92,32 @@ Optional Arguments
 
 **-C**
     Use the center of the block as the output location [Default uses the
-    median x and median y as location (but see |-Q|)].
+    median *x* and median *y* as location (but see |-Q|)].
 
 .. _-E:
 
-**-E**\ [**b**]
-    Provide Extended report which includes **s** (the L1 scale of the
-    median, i.e., 1.4826 \* median absolute deviation [MAD]), **l**, the lowest
-    value, and **h**, the high value for each block. Output order becomes
-    *x*,\ *y*,\ *z*,\ *s*,\ *l*,\ *h*\ [,\ *w*]. Default outputs
-    *x*,\ *y*,\ *z*\ [,\ *w*]. For box-and-whisker calculation, use
-    **-Eb** which will output
-    *x*,\ *y*,\ *z*,\ *l*,\ *q25*,\ *q75*,\ *h*\ [,\ *w*], where *q25* and
-    *q75* are the 25% and 75% quantiles, respectively. See |-W| for
-    *w* output.
-
-**-E**\ **r**\|\ **s**\ [**+l**\|\ **h**]
-    Provide source id **s** or record number **r** output, i.e., append
-    the source id or record number associated with the median value. If
-    tied then report the record number of the higher of the two values (i.e., **+h** is the default);
-    append **+l** to instead report the record number of the lower value.
-    Note that |-E| may be repeated so that both **-E**\ [**b**] and
-    **-E**\ **r**\ [**+l**\|\ **h**] can be
-    specified. For **-E**\ **s** we expect input records of the form
-    *x*,\ *y*,\ *z*\ [,\ *w*],\ *sid*, where *sid* is an unsigned integer
-    source id.
+**-E**\ [**b**\|\ **r**\|\ **s**\ [**+l**\|\ **h**]]
+    Provide Extended reporting beyond the default *x*,\ *y*,\ *z*\ [,\ *w*].
+    One of several directives affects what the extended output record contains.
+    In all cases, see |-W| for appending weights *w* to the output record:
+
+    - **b**: Write output suitable for box-and-whisker plots. Output will include
+      *x*,\ *y*,\ *z*,\ *l*,\ *q25*,\ *q75*,\ *h*\ [,\ *w*], where *q25* and *q75*
+      are the 25% and 75% quantiles, respectively.
+    - **r**: Append the record number associated with the median value. If tied then
+      report the record number of the higher of the two values (i.e., **+h** is the default).
+      Append **+l** to instead report the record number of the lower median value.
+    - **s**: Append the source id associated with the median value.  We expect input
+      records of the form *x*,\ *y*,\ *z*\ [,\ *w*],\ *sid*, where *sid* is an unsigned
+      integer source id. If tied then report the source id of the higher of the two
+      median values (i.e., **+h** is the default). Append **+l** to instead report
+      the source id of the lower median value.
+
+    If no directive is given then we compute *s*, the L1 scale of the median, i.e.,
+    1.4826 \* median absolute deviation [MAD]), *l*, the lowest value, and *h*, the highest
+    value for each block. Output order becomes *x*,\ *y*,\ *z*,\ *s*,\ *l*,\ *h*\ [,\ *w*].
+    **Note**: |-E| may be repeated so that both **-E**\ **r**\|\ **s**\ [**+l**\|\ **h**]
+    and **-E**\ [**b**] can be specified.
 
 .. _-G:
 

diff --git a/doc/rst/source/blockmode.rst b/doc/rst/source/blockmode.rst
@@ -96,35 +96,41 @@ Optional Arguments
 
 **-D**\ [*width*]\ [**+c**][**+a**\|\ **+l**\|\ **+h**]
     Perform unweighted mode calculation via histogram binning, using the
-    specified histogram *width*. Append **+c** to center bins so that
-    their mid point is a multiple of *width* [uncentered].
-    If multiple modes are found for a block we return the average mode [**+a**].
-    Append **+l** or **+h** to return the low of high mode instead, respectively.
-    If *width* is not given it will default to 1 provided your data set only
-    contains integers. Also, for integer data and integer bin *width* we
-    enforce bin centering (**+c**) and select the lowest mode (**+l**) if
-    there are multiples. [Default mode is normally the Least Median of Squares (LMS) statistic].
+    specified histogram *width*. A few modifiers are available to affect the output:
+
+    - **+c** Center bins so that their mid point is a multiple of *width* [uncentered].
+    - **+a** If multiple modes are found for a block we return the average mode [Default].
+    - **+l** If multiple modes are found for a block we return the lowest mode.
+    - **+h** If multiple modes are found for a block we return the highest mode.
+
+    Only one of **+a**\|\ **+l**\|\ **+h** may be selected.  If *width* is not
+    given it will default to 1 provided your data set only contains integers.
+    Also, for integer data and integer bin *width* we enforce bin centering (**+c**)
+    and select the lowest mode (**+l**) if there are multiples. [Default mode is
+    normally the Least Median of Squares (LMS) statistic].
 
 .. _-E:
 
-**-E**
-    Provide Extended report which includes **s** (the L1 scale of the
-    mode), **l**, the lowest value, and **h**, the high value for each
-    block. Output order becomes
-    *x*,\ *y*,\ *z*,\ *s*,\ *l*,\ *h*\ [,\ *w*]. Default outputs
-    *x*,\ *y*,\ *z*\ [,\ *w*]. See |-W| for *w* output.
-
-**-E**\ **r**\|\ **s**\ [**+l**\|\ **h**]
-    Provide source id **s** or record number **r** output, i.e., append
-    the source id or record number associated with the modal value. If
-    tied then report the record number of the higher of the two values (i.e., **+h** is the default);
-    append **+l** to instead report the record number of the lower value.
-    Note that |-E| may be repeated so that both both |-E| and
-    **-E**\ **r**\ [**+l**\|\ **h**] may be specified.
-    For **-E**\ **s** we expect input records of the form
-    *x*,\ *y*,\ *z*\ [,\ *w*],\ *sid*, where *sid* is an unsigned integer
-    source id.
-
+**-E**\ [**r**\|\ **s**\ [**+l**\|\ **h**]]
+    Provide Extended reporting beyond the default *x*,\ *y*,\ *z*\ [,\ *w*].
+    One of several directives affects what the extended output record contains.
+    In all cases, see |-W| for appending weights *w* to the output record:
+
+    - **r**: Append the record number associated with the modal value. If tied then
+      report the record number of the higher of the two values (i.e., **+h** is the default).
+      Append **+l** to instead report the record number of the lower modal value.
+    - **s**: Append the source id associated with the modal value.  We expect input
+      records of the form *x*,\ *y*,\ *z*\ [,\ *w*],\ *sid*, where *sid* is an unsigned
+      integer source id. If tied then report the source id of the higher of the two
+      modal values (i.e., **+h** is the default). Append **+l** to instead report
+      the source id of the lower modal value.
+
+    If no directive is given then we compute *s*, the L1 scale of the mode, i.e.,
+    1.4826 \* mode absolute deviation [MAD]), *l*, the lowest value, and *h*, the highest
+    value for each block. Output order becomes *x*,\ *y*,\ *z*,\ *s*,\ *l*,\ *h*\ [,\ *w*].
+    **Note**: |-E| may be repeated so that both **-E**\ **r**\|\ **s**\ [**+l**\|\ **h**]
+    and plain **-E** can be specified.
+
 .. _-G:
 
 **-G**\ *grdfile*

diff --git a/src/blockmode.c b/src/blockmode.c
@@ -162,20 +162,24 @@ static int parse (struct GMT_CTRL *GMT, struct BLOCKMODE_CTRL *Ctrl, struct GMT_
 			case 'D':	/* Histogram mode estimate */
 				n_errors += gmt_M_repeated_module_option (API, Ctrl->D.active);
 				Ctrl->D.width = atof (opt->arg);
-				pos = 0;
+				pos = k = 0;
 				if ((c = strchr (opt->arg, '+')) != NULL) {	/* Found modifiers */
 					while ((gmt_strtok (c, "+", &pos, p))) {
 						switch (p[0]) {
 							case 'c': Ctrl->D.center = true; break;	/* Center the histogram */
-							case 'a': Ctrl->D.mode = BLOCKMODE_AVE;  break;	/* Pick average mode */
-							case 'l': Ctrl->D.mode = BLOCKMODE_LOW;  break;	/* Pick low mode */
-							case 'h': Ctrl->D.mode = BLOCKMODE_HIGH; break;	/* Pick high mode */
+							case 'a': k++;	Ctrl->D.mode = BLOCKMODE_AVE;  break;	/* Pick average mode */
+							case 'l': k++;	Ctrl->D.mode = BLOCKMODE_LOW;  break;	/* Pick low mode */
+							case 'h': k++;	Ctrl->D.mode = BLOCKMODE_HIGH; break;	/* Pick high mode */
 							default:	/* Bad modifier */
 								GMT_Report (API, GMT_MSG_ERROR, "Unrecognized modifier +%c.\n", p[0]);
 								n_errors++;
 								break;
 						}
 					}
+					if (k > 1) {	/* Only one of +a|l|h can be selected */
+						GMT_Report (API, GMT_MSG_ERROR, "Option -D: Only one of +a, +l, and +h can be selected.\n");
+						n_errors++;
+					}
 				}
 				break;
 			case 'E':