r.neighbors: backport of https://trac.osgeo.org/grass/changeset/60345, https://trac.osgeo.org/grass/changeset/60346 (precision) and https://trac.osgeo.org/grass/changeset/60375 (manual)

git-svn-id: https://svn.osgeo.org/grass/grass/branches/releasebranch_7_0@60456 15284696-431f-4ddb-bdfa-cd5b030d7da7

raster/r.neighbors/main.c

@@ -37,33 +37,41 @@ struct menu
     ifunc cat_names;		/* routine to make category names */
     int copycolr;		/* flag if color table can be copied */
     int half;			/* whether to add 0.5 to result (redundant) */
-    int is_int;			/* result is an integer */
+    int otype;			/* output type */
     char *name;			/* method name */
     char *text;			/* menu display - full description */
 };
 
+enum out_type {
+    T_FLOAT	= 1,
+    T_INT	= 2,
+    T_COUNT	= 3,
+    T_COPY	= 4,
+    T_SUM	= 5
+};
+
 #define NO_CATS 0
 
 /* modify this table to add new methods */
 static struct menu menu[] = {
-    {c_ave, w_ave, NO_CATS, 1, 1, 0, "average", "average value"},
-    {c_median, w_median, NO_CATS, 1, 0, 0, "median", "median value"},
-    {c_mode, w_mode, NO_CATS, 1, 0, 0, "mode", "most frequently occuring value"},
-    {c_min, NULL, NO_CATS, 1, 0, 0, "minimum", "lowest value"},
-    {c_max, NULL, NO_CATS, 1, 0, 0, "maximum", "highest value"},
-    {c_range, NULL, NO_CATS, 1, 0, 0, "range", "range value"},
-    {c_stddev, w_stddev, NO_CATS, 0, 1, 0, "stddev", "standard deviation"},
-    {c_sum, w_sum, NO_CATS, 1, 0, 0, "sum", "sum of values"},
-    {c_count, w_count, NO_CATS, 0, 0, 1, "count", "count of non-NULL values"},
-    {c_var, w_var, NO_CATS, 0, 1, 0, "variance", "statistical variance"},
-    {c_divr, NULL, divr_cats, 0, 0, 1, "diversity",
+    {c_ave, w_ave, NO_CATS, 1, 1, T_FLOAT, "average", "average value"},
+    {c_median, w_median, NO_CATS, 1, 0, T_FLOAT, "median", "median value"},
+    {c_mode, w_mode, NO_CATS, 1, 0, T_COPY, "mode", "most frequently occuring value"},
+    {c_min, NULL, NO_CATS, 1, 0, T_COPY, "minimum", "lowest value"},
+    {c_max, NULL, NO_CATS, 1, 0, T_COPY, "maximum", "highest value"},
+    {c_range, NULL, NO_CATS, 1, 0, T_COPY, "range", "range value"},
+    {c_stddev, w_stddev, NO_CATS, 0, 1, T_FLOAT, "stddev", "standard deviation"},
+    {c_sum, w_sum, NO_CATS, 1, 0, T_SUM, "sum", "sum of values"},
+    {c_count, w_count, NO_CATS, 0, 0, T_COUNT, "count", "count of non-NULL values"},
+    {c_var, w_var, NO_CATS, 0, 1, T_FLOAT, "variance", "statistical variance"},
+    {c_divr, NULL, divr_cats, 0, 0, T_INT, "diversity",
      "number of different values"},
-    {c_intr, NULL, intr_cats, 0, 0, 1, "interspersion",
+    {c_intr, NULL, intr_cats, 0, 0, T_INT, "interspersion",
      "number of values different than center value"},
-    {c_quart1, w_quart1, NO_CATS, 1, 0, 0, "quart1", "first quartile"},
-    {c_quart3, w_quart3, NO_CATS, 1, 0, 0, "quart3", "third quartile"},
-    {c_perc90, w_perc90, NO_CATS, 1, 0, 0, "perc90", "ninetieth percentile"},
-    {c_quant, w_quant, NO_CATS, 1, 0, 0, "quantile", "arbitrary quantile"},
+    {c_quart1, w_quart1, NO_CATS, 1, 0, T_FLOAT, "quart1", "first quartile"},
+    {c_quart3, w_quart3, NO_CATS, 1, 0, T_FLOAT, "quart3", "third quartile"},
+    {c_perc90, w_perc90, NO_CATS, 1, 0, T_FLOAT, "perc90", "ninetieth percentile"},
+    {c_quant, w_quant, NO_CATS, 1, 0, T_FLOAT, "quantile", "arbitrary quantile"},
     {0, 0, 0, 0, 0, 0, 0, 0}
 };
 
@@ -96,6 +104,25 @@ static int find_method(const char *method_name)
     return -1;
 }
 
+static RASTER_MAP_TYPE output_type(RASTER_MAP_TYPE input_type, int weighted, int mode)
+{
+    switch (mode) {
+    case T_FLOAT:
+	return DCELL_TYPE;
+    case T_INT:
+	return CELL_TYPE;
+    case T_COUNT:
+	return weighted ? DCELL_TYPE : CELL_TYPE;
+    case T_COPY:
+	return input_type;
+    case T_SUM:
+	return weighted ? DCELL_TYPE : input_type;
+    default:
+	G_fatal_error(_("Invalid out_type enumeration: %d"), mode);
+	return -1;
+    }
+}
+
 int main(int argc, char *argv[])
 {
     char *p;
@@ -209,7 +236,6 @@ int main(int argc, char *argv[])
     parm.quantile->multiple = YES;
     parm.quantile->description = _("Quantile to calculate for method=quantile");
     parm.quantile->options = "0.0-1.0";
-    parm.quantile->answer = "0.5";
 
     flag.align = G_define_flag();
     flag.align->key = 'a';
@@ -285,6 +311,7 @@ int main(int argc, char *argv[])
 	const char *output_name = parm.output->answers[i];
 	const char *method_name = parm.method->answers[i];
 	int method = find_method(method_name);
+	RASTER_MAP_TYPE otype = output_type(map_type, weights, menu[method].otype);
 
 	out->name = output_name;
 	if (weights) {
@@ -322,8 +349,7 @@ int main(int argc, char *argv[])
 	    ? atof(parm.quantile->answers[i])
 	    : 0;
 	out->buf = Rast_allocate_d_buf();
-	out->fd = Rast_open_new(output_name,
-				(menu[method].is_int && !out->method_fn_w) ? CELL_TYPE : DCELL_TYPE);
+	out->fd = Rast_open_new(output_name, otype);
 	/* TODO: method=mode should propagate its type */
 
 	/* get title, initialize the category and stat info */

raster/r.neighbors/r.neighbors.html

@@ -11,7 +11,6 @@ value equal to the average of the values
 appearing in its 3 x 3 cell "neighborhood" in the input
 layer.
 
-
 <p>
 The program will be run non-interactively if the user
 specifies program arguments (see OPTIONS) on the command
@@ -307,6 +306,60 @@ for <em>average</em> neighborhood function output,
 whether or not the color file makes sense for the output
 will be dependent on the input data values.)
 
+<h3>Propagation of output precision</h3>
+
+The following logic has been implemented: For any aggregate, there are
+two factors affecting the output type:
+
+<ol>
+<li> Whether the input map is integer or floating-point.</li> 
+<li> Whether the weighted or unweighted version of the aggregate is used.</li> 
+</ol>
+
+These combine to create four possibilities:
+<p>
+<table border="1">
+ <tr><th>input type</th><th>integer</th><th>integer</th><th>float</th><th>float</th></tr>
+ <tr><td>weighted</td><td>no</td><td>yes</td><td>no</td><td>yes</td></tr>
+ <tr><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td></tr>
+ <tr><td>average</td><td>float</td><td>float</td><td>float</td><td>float</td></tr>
+ <tr><td>median</td><td>[1]</td><td>[1]</td><td>float</td><td>float</td></tr>
+ <tr><td>mode</td><td>integer</td><td>integer</td><td>[2]</td><td>[2]</td></tr>
+ <tr><td>minimum</td><td>integer</td><td>integer</td><td>float</td><td>float</td></tr>
+ <tr><td>maximum</td><td>integer</td><td>integer</td><td>float</td><td>float</td></tr>
+ <tr><td>range</td><td>integer</td><td>integer</td><td>float</td><td>float</td></tr>
+ <tr><td>stddev</td><td>float</td><td>float</td><td>float</td><td>float</td></tr>
+ <tr><td>sum</td><td>integer</td><td>float</td><td>float</td><td>float</td></tr>
+ <tr><td>count</td><td>integer</td><td>float</td><td>integer</td><td>float</td></tr>
+ <tr><td>variance</td><td>float</td><td>float</td><td>float</td><td>float</td></tr>
+ <tr><td>diversity</td><td>integer</td><td>integer</td><td>integer</td><td>integer</td></tr>
+ <tr><td>interspersion</td><td>integer</td><td>integer</td><td>integer</td><td>integer</td></tr>
+ <tr><td>quart1</td><td>[1]</td><td>[1]</td><td>float</td><td>float</td></tr>
+ <tr><td>quart3</td><td>[1]</td><td>[1]</td><td>float</td><td>float</td></tr>
+ <tr><td>perc90</td><td>[1]</td><td>[1]</td><td>float</td><td>float</td></tr>
+ <tr><td>quantile</td><td>[1]</td><td>[1]</td><td>float</td><td>float</td></tr>
+</table>
+<p>
+[1] For integer input, quantiles may produce float results from
+interpolating between adjacent values.
+<br>
+[2] Calculating the mode of floating-point data is essentially
+meaningless.
+<p>
+	
+With the current aggregates, there are 5 cases:
+
+<ol> 
+<li> Output is always float: average, variance, stddev, quantiles (with
+interpolation).</li> 
+<li> Output is always integer: diversity, interspersion.</li> 
+<li> Output is integer if unweighted, float if weighted: count.</li> 
+<li> Output matches input: minimum, maximum, range, mode (subject to
+note 2 above), quantiles (without interpolation).</li> 
+<li> Output is integer for integer input and unweighted aggregate,
+otherwise float: sum.</li> 
+</ol> 
+
 <!-- TODO
 <h2>EXAMPLES</h2>
 
@@ -326,9 +379,11 @@ r.neighbors
 <em><a href="r.support.html">r.support</a></em>
 
 
-<h2>AUTHOR</h2>
+<h2>AUTHORS</h2>
 
-Michael Shapiro,
+Original version: Michael Shapiro,
 U.S.Army Construction Engineering Research Laboratory 
+<br>
+Updates for GRASS GIS 7 by Glynn Clements and others
 
 <p><i>Last changed: $Date$</i>