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'  cate-
       gories 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 specifying 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	simply	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 coincidence analysis.  _r_._c_o_i_n then tabulates the coin-
       cidence 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 important 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 percentage 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
       letters	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 out-
       put is stated in units of square miles.	The report tabulates the coin-
       cidence 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.  For-
       est Service (category 2). The _r_o_a_d_s map layer categories refer to vari-
       ous types of roads (with the exception 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 vertical axis of the  table;  the
       other,  along the horizontal axis.  Each panel has a maximum of 5 cate-
       gories (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 cate-
       gories of the map layer arranged along the vertical axis  are  included
       in  each  panel.   There is a total at the bottom of each column repre-
       senting the sum of all the rows in that column. A second  total	repre-
       sents  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 Forest 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 mon-
       strous 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 categories (using _r_e_c_l_a_s_s) into a more manageable num-
       ber 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 layers.  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

       _m_._i_p_f

       _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_3_/_0_3_/_1_6 _1_2_:_2_5_:_1_9 _$



GRASS 5.0							     r.coin(1)
