Geografic-Information-System/raster/r.coin/r.coin.html

<h2>DESCRIPTION</h2>

<em>r.coin</em> 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.

<p>
<em>r.coin</em>
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 important after all, and may cancel
the request at this point.  Assuming the user continues,
<em>r.coin</em> then allows the user to choose one of eight
units of measure in which the report results can be given.
These units are:

<p>
<dl>
<dt><em>c</em> <dd>cells 
<dt><em>p</em> <dd>percent cover of region 
<dt><em>x</em> <dd>percent of &lt;map name&gt; category (column) 
<dt><em>y</em> <dd>percent of &lt;map name&gt; category (row) 
<dt><em>a</em> <dd>acres 
<dt><em>h</em> <dd>hectares 
<dt><em>k</em> <dd>square kilometers 
<dt><em>m</em> <dd>square miles 
</dl>

<p>
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
&lt;RETURN&gt;.  The report will be printed to the screen
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.

<h2>NOTES</h2>

It is <b>not</b> a good idea to run <em>r.coin</em> on a
map layer which has a monstrous number of categories (e.g.,
unreclassed elevation).  Because <em>r.coin</em> reports
information for each and every category, it is better to
reclassify those categories (using <em>r.reclass</em>)
into a more manageable number prior to running
<em>r.coin</em> on the reclassed raster map layer.

<h2>EXAMPLE</h2>

Below is a sample of tabular output produced by
<em>r.coin</em>.  Here, map output is stated in units of
square miles.  The report tabulates the coincidence of the
Spearfish sample database's <em>owner</em> and
<em>road</em> raster map layers' categories.  The
<em>owner</em> 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 <em>roads</em> map
layer categories refer to various types of roads (with the
exception of category value "0", which indicates "no data";
i.e., map locations at which no roads exist).
<em>r.coin</em> does not report category labels. The user
should run
<em><a href="r.report.html">r.report</a></em> or 
<em><a href="r.category.html">r.category</a></em> 
to obtain this information. 

<p>
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 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 vertical
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.

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

<p>
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.
<p>Of the total 102.70 square miles in Spearfish, 42.80 
square miles is owned by the Forest Service. 
<br>
In total, there are 14.58 square miles of roads. 
<p>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.). 

<p>Following is a sample report. 

<div class="code"><pre>
+------------------------------------------------------------+
|                    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 |
+--------------------------------+
</pre></div>

<p>
<em>r.coin</em> calculates the coincidence of two raster
map layers.  Although <em>r.coin</em> 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
<em>r.coin.</em>

<!-- North Carolina sample dataset:

Show percentage of each landclass for each town as well as
the summaries:

<div class="code"><pre>
g.region raster=landclass96,towns -p
r.cats landclass96
r.cats towns
r.coin -w first=landclass96 second=towns unit=p
</pre></div>

The result shows that 60% of the current region is located
in South Raleigh, about half of the area is covered by
forest and 30% is developed.
-->

<h2>SEE ALSO</h2>

<em>
<a href="g.region.html">g.region</a>,
<!-- not ported to GRASS 6 <a href="m.ipf.html">m.ipf</a>, -->
<a href="r.category.html">r.category</a>,
<a href="r.describe.html">r.describe</a>,
<a href="r.reclass.html">r.reclass</a>,
<a href="r.report.html">r.report</a>,
<a href="r.stats.html">r.stats</a>
</em>

<h2>AUTHORS</h2>

Michael O'Shea, 
<br>
Michael Shapiro, <br>
U.S. Army Construction Engineering Research Laboratory

<p><i>Last changed: $Date$</i>