diff --git a/doc/rst/source/blockmean.rst b/doc/rst/source/blockmean.rst index b1d76f115f5..5af1d8710ac 100644 --- 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 index d04f5398350..47a6fd460b3 100644 --- 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 index b115a563df1..cbdb3f69be1 100644 --- 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 index 2b00cd01446..5cf86ed1a21 100644 --- 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':