# areamat

Surface area covered by nonzero values in binary data grid

## Syntax

```A = areamat(BW,R) A = areamat(BW,refvec,ellipsoid) [A, cellarea] = areamat(...) ```

## Description

`A = areamat(BW,R)` returns the surface area covered by the elements of the binary regular data grid `BW`, which contain the value 1 (`true`). `BW` can be the result of a logical expression such as ```BW = (topo > 0)```. `R` can be a geographic raster reference object, a referencing vector, or a referencing matrix.

If `R` is a geographic raster reference object, its `RasterSize` property must be consistent with `size(BW)` and its `RasterInterpretation` must be `'cells'`.

If `R` is a referencing vector, it must be a 1-by-3 with elements:

`[cells/degree northern_latitude_limit western_longitude_limit]`

If `R` is a referencing matrix, it must be 3-by-2 and transform raster row and column indices to or from geographic coordinates according to:

`[lon lat] = [row col 1] * R`

If `R` is a referencing matrix, it must define a (non-rotational, non-skewed) relationship in which each column of the data grid falls along a meridian and each row falls along a parallel. Nearest-neighbor interpolation is used by default. NaN is returned for points outside the grid limits or for which `lat` or `lon` contain NaN. All angles are in units of degrees.

The output `A` expresses surface area as a fraction of the surface area of the unit sphere (4*pi), so the result ranges from 0 to 1.

`A = areamat(BW,refvec,ellipsoid)` calculates the surface area on the ellipsoid or sphere defined by the input `ellipsoid`, which can be a `referenceSphere`, `referenceEllipsoid`, or `oblateSpheroid` object, or a vector of the form ```[semimajor_axis eccentricity]```. The units of the output, `A`, are the square of the length units in which the semimajor axis is provided. For example, if `ellipsoid` is replaced with `wgs84Ellipsoid('kilometers')`, then `A` is in square kilometers.

`[A, cellarea] = areamat(...)` returns a vector, `cellarea`, describing the area covered by the data cells in `BW`. Because all the cells in a given row are exactly the same size, only one value is needed per row. Therefore `cellarea` has size `M-by-1`, where `M = size(BW,1)` is the number of rows in `BW`.

## Examples

```load topo area = areamat((topo>127),topolegend) area = 0.2411```

Approximately 24% of the Earth has an altitude greater than 127 meters. The surface area of this portion of the Earth in square kilometers if a spherical ellipsoid is:

```earth = referenceSphere('earth', 'km'); area = areamat((topo>127),topolegend,earth) area = 1.2299e+08```

To illustrate the `cellarea` output, consider a smaller map:

```BW = ones(9,18); refvec = [.05 90 0] % each cell 20x20 degrees [area,cellarea] = areamat(BW,refvec) area = 1.0000 cellarea = 0.0017 0.0048 0.0074 0.0091 0.0096 0.0091 0.0074 0.0048 0.0017```

Each entry of `cellarea` represents the portion of the unit sphere's total area a cell in that row of `BW` would contribute. Since the column extends from pole to pole in this case, it is symmetric.

## Tips

Given a regular data grid that is a logical 0-1 matrix, the `areamat` function returns the area corresponding to the true, or 1, elements. The input data grid can be a logical statement, such as `(topo>0)`, which is 1 everywhere that `topo` is greater than 0 meters, and 0 everywhere else. This is an illustration of that matrix: This calculation is based on the `areaquad` function and is therefore limited only by the granularity of the cellular data. 