r.report: implemente 'sort' parameter

          major update of manual page
          guisection cosmetics


git-svn-id: https://svn.osgeo.org/grass/grass/trunk@58399 15284696-431f-4ddb-bdfa-cd5b030d7da7

raster/r.report/global.h

@@ -7,6 +7,10 @@
 
 #include <grass/raster.h>
 
+#define SORT_DEFAULT 0
+#define SORT_ASC     1
+#define SORT_DESC    2
+
 extern struct Cell_head window;
 
 struct _layer_
@@ -57,6 +61,7 @@ extern int with_headers;
 extern int e_format;
 extern int no_nulls;
 extern int no_nulls_all;
+extern int do_sort;
 
 extern char *stats_file;
 extern char *no_data_str;

raster/r.report/main.c

@@ -6,8 +6,9 @@
  *               Roberto Flor <flor itc.it>
  *               Jachym Cepicky <jachym les-ejk.cz>, 
  *               Jan-Oliver Wagner <jan intevation.de>
+ *               Sort option by Martin Landa <landa.martin gmail.com>
  * PURPOSE:      Reports statistics for raster map(s).
- * COPYRIGHT:    (C) 1999-2006, 2011 by the GRASS Development Team
+ * COPYRIGHT:    (C) 1999-2013 by the GRASS Development Team
  *
  *               This program is free software under the GNU General
  *               Public License (>=v2). Read the file COPYING that
@@ -36,10 +37,10 @@ int masking = 1;
 int use_formfeed;
 int nlines;
 int with_headers = 1;
-int verbose = 1;
 int e_format;
 int no_nulls;
 int no_nulls_all;
+int do_sort = SORT_DEFAULT;
 
 char *stats_file;
 char *no_data_str;

raster/r.report/parse.c

@@ -19,6 +19,7 @@ int parse_command_line(int argc, char *argv[])
 	struct Option *outfile;
 	struct Option *nv;
 	struct Option *nsteps;
+        struct Option *sort;
     } parms;
     struct
     {
@@ -36,27 +37,34 @@ int parse_command_line(int argc, char *argv[])
     } flags;
 
     parms.cell = G_define_standard_option(G_OPT_R_MAPS);
-    parms.cell->description = _("Raster map(s) to report on");
+    parms.cell->description = _("Name of raster map(s) to report on");
 
     parms.units = G_define_option();
     parms.units->key = "units";
     parms.units->type = TYPE_STRING;
     parms.units->required = NO;
     parms.units->multiple = YES;
-    parms.units->description = _("Units");
+    parms.units->description = _("Units to report");
     desc = NULL;
     G_asprintf(&desc,
 	       "mi;%s;me;%s;k;%s;a;%s;h;%s;c;%s;p;%s",
-	       _("miles"),
-	       _("meters"),
-	       _("kilometers"),
-	       _("acres"),
-	       _("hectares"),
-	       _("cell counts"),
+	       _("area in square miles"),
+	       _("area in square meters"),
+	       _("area in square kilometers"),
+	       _("area in acres"),
+	       _("area in hectares"),
+	       _("number of cells"),
 	       _("percent cover"));
     parms.units->descriptions = desc;
     parms.units->options = "mi,me,k,a,h,c,p";
-    parms.units->guisection = _("Output settings");
+    parms.units->guisection = _("Statistics");
+
+    parms.outfile = G_define_standard_option(G_OPT_F_OUTPUT);
+    parms.outfile->required = NO;
+    parms.outfile->label =
+	_("Name for output file to hold the report");
+    parms.outfile->description =
+	_("If no output given report is printed to standard output");
 
     parms.nv = G_define_option();
     parms.nv->key = "null";
@@ -64,7 +72,7 @@ int parse_command_line(int argc, char *argv[])
     parms.nv->required = NO;
     parms.nv->multiple = NO;
     parms.nv->answer = "*";
-    parms.nv->description = _("Character representing no data cell value");
+    parms.nv->description = _("String representing no data cell value");
     parms.nv->guisection = _("Formatting");
 
     parms.pl = G_define_option();
@@ -85,15 +93,6 @@ int parse_command_line(int argc, char *argv[])
     parms.pw->description = pw_desc;
     parms.pw->guisection = _("Formatting");
 
-    parms.outfile = G_define_standard_option(G_OPT_F_OUTPUT);
-    parms.outfile->key = "output";
-    parms.outfile->required = NO;
-    parms.outfile->label =
-	_("Name for output file to hold the report");
-    parms.outfile->description =
-	_("If no output given report is printed to standard output");
-    parms.outfile->guisection = _("Output settings");
-
     parms.nsteps = G_define_option();
     parms.nsteps->key = "nsteps";
     parms.nsteps->type = TYPE_INTEGER;
@@ -101,8 +100,22 @@ int parse_command_line(int argc, char *argv[])
     parms.nsteps->multiple = NO;
     parms.nsteps->answer = "255";
     parms.nsteps->description =
-	_("Number of fp subranges to collect stats from");
-    parms.nsteps->guisection = _("FP maps");
+	_("Number of floating-point subranges to collect stats from");
+    parms.nsteps->guisection = _("Floating point");
+
+    parms.sort = G_define_option();
+    parms.sort->key = "sort";
+    parms.sort->type = TYPE_STRING;
+    parms.sort->required = NO;
+    parms.sort->multiple = NO;
+    parms.sort->label = _("Sort output statistics by cell counts");
+    parms.sort->description = _("Default: sorted by categories or intervals");
+    parms.sort->options = "asc,desc";
+    G_asprintf((char **)&(parms.sort->descriptions),
+               "asc;%s;desc;%s",
+               _("Sort by cell counts in ascending order"),
+               _("Sort by cell counts in descending order"));
+    parms.sort->guisection = _("Formatting");
 
     flags.h = G_define_flag();
     flags.h->key = 'h';
@@ -122,21 +135,23 @@ int parse_command_line(int argc, char *argv[])
     flags.n = G_define_flag();
     flags.n->key = 'n';
     flags.n->description = _("Filter out all no data cells");
+    flags.n->guisection = _("No data");
 
     flags.N = G_define_flag();
     flags.N->key = 'N';
     flags.N->description = _("Filter out cells where all maps have no data");
+    flags.N->guisection = _("No data");
 
     flags.C = G_define_flag();
     flags.C->key = 'C';
-    flags.C->description = _("Report for cats fp ranges (fp maps only)");
-    flags.C->guisection = _("FP maps");
+    flags.C->description = _("Report for cats floating-point ranges (floating-point maps only)");
+    flags.C->guisection = _("Floating point");
 
     flags.i = G_define_flag();
     flags.i->key = 'i';
     flags.i->description =
-	_("Read fp map as integer (use map's quant rules)");
-    flags.i->guisection = _("FP maps");
+	_("Read floating-point map as integer (use map's quant rules)");
+    flags.i->guisection = _("Floating point");
 
     /* hidden feature.
      * if first arg is >file just run r.stats into this file and quit
@@ -203,6 +218,22 @@ int parse_command_line(int argc, char *argv[])
     }
     no_data_str = parms.nv->answer;
 
+    /* determine sorting method */
+    do_sort = SORT_DEFAULT; /* sort by cats by default */
+    if (parms.sort->answer) {
+        switch(parms.sort->answer[0]) {
+        case 'a':
+            do_sort = SORT_ASC;
+            break;
+        case 'd':
+            do_sort = SORT_DESC;
+            break;
+        default:
+            G_debug(1, "Sorting by '%s' not supported", parms.sort->answer);
+            break;
+        }
+    }
+
     return 0;
 }
 

raster/r.report/r.report.html

@@ -1,104 +1,103 @@
 <h2>DESCRIPTION</h2>
 
-<em>r.report</em> allows the user to set up a series of report parameters to
-be applied to a raster map layer, and creates a report.  If invoked with
-command line arguments, the report will print out to the screen only.
-However, output may be redirected to a file or another program using the
-UNIX redirection mechanism. If invoked without command line arguments, the
-user is given the option of printing out each report and/or saving output to
-a file.
-
-<p>The report itself consists of two parts, a header section and the main body
-of the report.
-
-<p>The header section of the report identifies the raster map layer(s) (by map
-layer name and TITLE), location, mapset, report date, and the region of
-interest. The area of interest is described in two parts: the user's current
-geographic region is presented, and the mask is presented (if any is used).
-
-<p>The main body of the report consists of from one to three tables which
-present the statistics for each category and the totals for each unit
-column.
-
-<p>Note that, unlike <em><a href="r.stats.html">r.stats</a></em>,
-<em>r.report</em> allows the user to select the specific units of measure in
-which statistics will be reported.
-
-<p>Following is the result of a <em>r.report</em> run on the raster map layer
-<em>geology</em> (located in the Spearfish, SD sample data base), with the
-units expressed in square miles and acres. Here, <em>r.report</em> output is
-directed into the file <em>report.file</em>.
-
-<h2>EXAMPLE:</h2>
-<dl>
-<dd>
-<b>r.report map=</b><em>geology</em> <b>units=</b><em>miles,acres</em> &gt; <em>report.file </em>
-</dl>
-
-<pre>
- ____________________________________________________________
-|                 RASTER MAP CATEGORY REPORT                 |
-| LOCATION: spearfish                      Fri Sep 2 09:20:09|
-|____________________________________________________________|
-|           north:   4928000.00   east:   609000.00          |
-| REGION:   south:   4914000.00   west:   590000.00          |
-|           res:         100.00   res:       100.00          |
-|____________________________________________________________|
-| MASK:     none                                             |
-|____________________________________________________________|
-| MAP:      geology in PERMANENT                             |
-|____________________________________________________________|
-|         Category Information     |    Acres       Square   |
-|    #      description            |                Miles    |
-|________|_________________________|_________________________|
-|    0   |  no data                |     415.13|      0.65   |
-|    1   |  metamorphic            |    2597.02|      4.06   |
-|    2   |  transition             |      32.12|      0.05   |
-|    3   |  igneous                |    8117.24|     12.68   |
-|    4   |  sandstone              |   16691.60|     26.08   |
-|    5   |  limestone              |   13681.93|     21.38   |
-|    6   |  shale                  |   10304.07|     16.10   |
-|    7   |  sandy shale            |    2517.95|      3.93   |
-|    8   |  claysand               |    3229.60|      5.05   |
-|    9   |  sand                   |    8141.95|     12.72   |
-|__________________________________|___________|_____________|
-|                 TOTAL            |   65728.60|    102.70   |
-|__________________________________|___________|_____________|
-</pre>
+<em>r.report</em> allows the user to set up a series of report
+parameters to be applied to a raster map, and creates a report. The
+report will print out to the standard output if <b>output</b>
+parameter is not given.
+
+<p>
+The report itself consists of two parts, a header section and the main
+body of the report.
 
+<p>
+The header section of the report identifies the raster map(s) (by map
+name and title), location, mapset, report date, and the region of
+interest. The area of interest is described in two parts: the user's
+current geographic region is presented, and the mask is presented (if
+any is used).
+
+<p>
+The main body of the report consists of from one to three tables which
+present the statistics for each category and the totals for each unit
+column. Note that the statistics is always computed in the current
+geographical region.
 
 <h2>NOTES</h2>
 
+<!--
 If the user runs <em>r.report</em> interactively and saves the report output
 in a file, this file will be placed into the user's current working
 directory.
 
-<p>
 If the user runs <em>r.report</em> non-interactively, report output can be
 saved by redirecting it to a file or a printer using the UNIX redirection
 mechanism.
-
-<p>
-To output computer-friendly data suitable for importing into a spreadsheet
-use the <em>r.stats</em> module. In fact <em>r.report</em> is running
-<em>r.stats</em> in the background and reformatting the results to be
-more human-friendly.
-
+-->
+
+Note that, unlike <em><a href="r.stats.html">r.stats</a></em>,
+<em>r.report</em> allows the user to select the specific units of
+measure in which statistics will be reported. To output
+computer-friendly data suitable for importing into a spreadsheet use
+the <em><a href="r.stats.html">r.stats</a></em> module. In
+fact <em>r.report</em> is running
+<em><a href="r.stats.html">r.stats</a></em> in the background and
+reformatting the results to be more human-friendly.
+
+<h2>EXAMPLE</h2>
+
+Report sorted areas in square miles and acres for each
+category. No-data are not reported (see <b>-n</b> flag).
+
+<div class="code"><pre>
+r.report -n map=geology_30m units=mi,a sort=desc
+
++-----------------------------------------------------------------------------+
+|                         RASTER MAP CATEGORY REPORT                          |
+|LOCATION: nc_spm_08_grass7                           Fri Dec  6 17:00:21 2013|
+|-----------------------------------------------------------------------------|
+|          north: 279073.97546639    east: 798143.31179672                    |
+|REGION    south: 113673.97546639    west: 595143.31179672                    |
+|          res:               200    res:              200                    |
+|-----------------------------------------------------------------------------|
+|MASK: none                                                                   |
+|-----------------------------------------------------------------------------|
+|MAP: South-West Wake county: geology derived from vector map (geology_30m in |
+|-----------------------------------------------------------------------------|
+|                 Category Information                  |    square|          |
+|  #|description                                        |     miles|     acres|
+|-----------------------------------------------------------------------------|
+|217|CZfg . . . . . . . . . . . . . . . . . . . . . . . | 27.783911|17,781.703|
+|270|CZig . . . . . . . . . . . . . . . . . . . . . . . | 26.162282|16,743.861|
+|405|CZbg . . . . . . . . . . . . . . . . . . . . . . . |  9.698886|  6207.287|
+|262|CZlg . . . . . . . . . . . . . . . . . . . . . . . |  7.629379|  4882.802|
+|862|CZam . . . . . . . . . . . . . . . . . . . . . . . |  2.532830|  1621.011|
+|910|CZbg . . . . . . . . . . . . . . . . . . . . . . . |  1.683405|  1077.379|
+|583|CZve . . . . . . . . . . . . . . . . . . . . . . . |  0.972977|   622.706|
+|921|Km . . . . . . . . . . . . . . . . . . . . . . . . |  0.463323|   296.526|
+|766|CZg. . . . . . . . . . . . . . . . . . . . . . . . |  0.324326|   207.569|
+|720|CZam . . . . . . . . . . . . . . . . . . . . . . . |  0.185329|   118.611|
+|946|CZam . . . . . . . . . . . . . . . . . . . . . . . |  0.138997|    88.958|
+|948|CZam . . . . . . . . . . . . . . . . . . . . . . . |  0.030888|    19.768|
+|-----------------------------------------------------------------------------|
+|TOTAL                                                  | 77.606534|49,668.182|
++-----------------------------------------------------------------------------+
+</div>
 
 <h2>SEE ALSO</h2>
 
-<em><a href="g.region.html">g.region</a>,
+<em>
+<a href="r.stats.html">r.stats</a>,
+<a href="g.region.html">g.region</a>,
 <a href="r.coin.html">r.coin</a>,
 <a href="r.describe.html">r.describe</a>,
 <a href="r.info.html">r.info</a>,
-<a href="r.stats.html">r.stats</a>,
 <a href="r.univar.html">r.univar</a>
 </em>
 
+<h2>AUTHORS</h2>
 
-<h2>AUTHOR</h2>
-Michael Shapiro,
-U.S. Army Construction Engineering Research Laboratory
+Michael Shapiro, U.S. Army Construction Engineering Research Laboratory<br>
+Sort option by Martin Landa, Czech Technical University in Prague, 2013
 
 <p>
 <i>Last changed: $Date$</i>

raster/r.report/stats.c

@@ -54,6 +54,11 @@ int get_stats(void)
 	argv[argc++] = SF_MODE_OUT;
 	argv[argc++] = stats_file;
 
+        if (do_sort == SORT_ASC)
+            argv[argc++] = "sort=asc";
+        else if (do_sort == SORT_DESC)
+            argv[argc++] = "sort=desc";
+        
 	for (i = 0; i < nlayers; i++) {
 	    char *name = G_fully_qualified_name(layers[i].name, layers[i].mapset);
 	    char *buf = G_malloc(6 + strlen(name) + 1);