r.coin(1)	       Grass User's Manual		r.coin(1)



NNAAMMEE
       rr..ccooiinn  - Tabulates the mutual occurrence (coincidence) of
       categories for two raster map layers.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..ccooiinn
       rr..ccooiinn hheellpp
       rr..ccooiinn [--qqww] mmaapp11==_n_a_m_e mmaapp22==_n_a_m_e uunniittss==_n_a_m_e

DDEESSCCRRIIPPTTIIOONN
       _r_._c_o_i_n tabulates the mutual occurrence of two  raster  map
       layers'	categories  with  respect  to  one another.  This
       analysis program respects the  current  geographic  region
       and mask settings.


       The user can run the program non-interactively by specify-
       ing all needed flags settings and parameter values on  the
       command line, in the form:


       rr..ccooiinn [--qqww] mmaapp11==_n_a_m_e mmaapp22==_n_a_m_e uunniittss==_n_a_m_e




   FFllaaggss::
       --qq     Run  quietly,  and  supress the printing of program
	      status messages to standard output.

       --ww     Print a wide report, in 132  columns  (default:  80
	      columns)




   PPaarraammeetteerrss::
       mmaapp11==_n_a_m_e
	      Name of first raster map layer.

       mmaapp22==_n_a_m_e
	      Name of second raster map layer.

       uunniittss==_n_a_m_e
	      Units of measure in which to output report results.
	      Options: _c_, _p_, _x_, _y_, _a_, _h_, _k_, _m



       Alternately, the user can run _r_._c_o_i_n interactively by sim-
       ply  typing rr..ccooiinn without command line arguments; in this
       case, the user will be prompted for the names of  the  two
       raster  map layers which will be the subjects of the coin-
       cidence analysis.  _r_._c_o_i_n then tabulates  the  coincidence
       of  category  values among the two map layers and prepares
       the basic table from which the report is  to  be  created.
       This  tabulation  is followed by an indication of how long
       the coincidence table will be.  If the table is	extremely
       long, the user may decide that viewing it is not so impor-
       tant after all, and may cancel the request at this  point.
       Assuming  the  user continues, _r_._c_o_i_n then allows the user
       to choose one of eight  units  of  measure  in  which  the
       report results can be given.  These units are:



       _c cells

       _p percent cover of region

       _x percent of  category (column)

       _y percent of  category (row)

       _a acres

       _h hectares

       _k square kilometers

       _m square miles



       Note  that three of these options give results as percent-
       age values:  "p" is based on the  grand	total  number  of
       cells;  "x"  is	based  on  only column totals; and "y" is
       based on only row totals.  Only one unit of measure can be
       selected  per report output.  Type in just one of the let-
       ters designating a unit	of  measure  followed  by  a  for
       review.	 After	reviewing  the	report on the screen, the
       user is given several options.  The report may be saved to
       a  file	and/or	sent to a printer.  If printed, it may be
       printed with either 80 or 132 columns.  Finally, the  user
       is  given  the  option to rerun the coincidence tabulation
       using a different unit of measurement.


       Below is a sample of tabular output  produced  by  _r_._c_o_i_n.
       Here,  map output is stated in units of square miles.  The
       report tabulates the coincidence of the	Spearfish  sample
       database's  _o_w_n_e_r  and _r_o_a_d raster map layers' categories.
       The _o_w_n_e_r categories in this case  refer  to  whether  the
       land  is  in private hands (category 1) or is owned by the
       U.S. Forest Service (category 2). The _r_o_a_d_s map layer cat-
       egories	refer  to various types of roads (with the excep-
       tion of category value "0",  which  indicates  "no  data";
       i.e., map locations at which no roads exist).  _r_._c_o_i_n does
       not report category labels. The user should  run  _r_._r_e_p_o_r_t
       or _r_._c_a_t_s to obtain this information.


       The  body  of  the  report  is arranged in panels. The map
       layer with the most categories is arranged along the  ver-
       tical  axis  of the table; the other, along the horizontal
       axis.  Each panel has a maximum	of  5  categories  (9  if
       printed) across the top. In addition, the last two columns
       reflect a cross total of each column for each row.  All of
       the  categories of the map layer arranged along the verti-
       cal axis are included in each panel.  There is a total  at
       the  bottom of each column representing the sum of all the
       rows in that column. A second total represents the sum  of
       all  the  non-zero category rows. A cross total (Table Row
       Total) of all columns for each row appears in  a  separate
       panel.


       Note  how  the  following information may be obtained from
       the sample report.


       In the Spearfish data base, in area not owned by the  For-
       est Service, there are 50.63 square miles of land not used
       for roads. Roads make up 9.27 square miles of land in this
       area.


       Of  the	total  102.70  square  miles  in Spearfish, 42.80
       square miles is owned by the Forest Service.
       In total, there are 14.58 square miles of roads.


       There are more category 2  roads  outside  Forest  Service
       land  (2.92  mi.  sq.)	than there are inside Forest land
       boundaries (0.72 mi. sq.).


       Following is a sample report.

       +------------------------------------------------------------+
       |		       COINCIDENCE    TABULATION   REPORT
       |
       |------------------------------------------------------------|
       |Location:  spearfish	Mapset: PERMANENT   Date: Wed Jun
       1  |
       |
       |
       |     Layer     1:     owner		 --	Ownership
       |
       |     Layer	2:	roads		    --	    Roads
       |
       |		       Mask:			     none
       |
       |
       |
       |	     Units:		  square	    miles
       |
       |------------------------------------------------------------|
       |       Window:			   North:      4928000.00
       |
       |	  West: 590000.00		 East:	609000.00
       |
       |				South:	       4914000.00
       |
       +------------------------------------------------------------+

       Panel #1 of 1
       +--------------------------------------------------------+
       |	| owner 		|    Panel Row Total	|
       |   cat# |	  1 |	      2 |   w cat 0 | w/o cat 0 |
       |--------------------------------------------------------|
       |r     0 |     50.63 |	  37.49 |     88.12 |	  88.12 |
       |o     1 |      1.53 |	   0.68 |      2.21 |	   2.21 |
       |a     2 |      2.92 |	   0.72 |      3.64 |	   3.64 |
       |d     3 |      3.97 |	   2.57 |      6.54 |	   6.54 |
       |s     4 |      0.65 |	   1.36 |      2.00 |	   2.00 |
       |      5 |      0.19 |	   0.00 |      0.19 |	   0.19 |
       |--------------------------------------------------------|
       |Total	|	    |		|	    |		|
       |with 0	|     59.90 |	  42.80 |    102.70 |	 102.70 |
       |--------------------------------------------------------|
       |w/o 0	|      9.27 |	   5.32 |     14.58 |	  14.58 |
       +--------------------------------------------------------+


       +--------------------------------+
       |	|    Table Row Total	|
       |   cat# |   w cat 0 | w/o cat 0 |
       |--------------------------------|
       |r     0 |     88.12 |	  88.12 |
       |o     1 |      2.21 |	   2.21 |
       |a     2 |      3.64 |	   3.64 |
       |d     3 |      6.54 |	   6.54 |
       |s     4 |      2.00 |	   2.00 |
       |      5 |      0.19 |	   0.19 |
       |--------------------------------|
       |Total	|	    |		|
       |with 0	|    102.70 |	 102.70 |
       |--------------------------------|
       |w/o 0	|     14.58 |	  14.58 |
       +--------------------------------+


NNOOTTEESS
       It  is  nnoott a good idea to run _r_._c_o_i_n on a map layer which
       has a monstrous number of  categories  (e.g.,  unreclassed
       elevation).   Because  _r_._c_o_i_n reports information for each
       and every category, it is better to reclassify those cate-
       gories (using _r_e_c_l_a_s_s) into a more manageable number prior
       to running _r_._c_o_i_n on the reclassed raster map layer.


       _r_._c_o_i_n calculates the coincidence of two raster	map  lay-
       ers.   Although _r_._c_o_i_n allows the user to rerun the report
       using different units, it is not possible to simply  rerun
       the  report with different map layers.  In order to choose
       new map layers, it is necessary to rerun _r_._c_o_i_n_.

SSEEEE AALLSSOO
       _g_._r_e_g_i_o_n

       _r_._c_a_t_s

       _r_._d_e_s_c_r_i_b_e

       _r_._m_a_s_k

       _r_._r_e_c_l_a_s_s

       _r_._r_e_p_o_r_t

       _r_._s_t_a_t_s

AAUUTTHHOORRSS
       Michael O'Shea,
       Michael Shapiro,

       U.S. Army Construction Engineering Research Laboratory

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0						r.coin(1)
