tmaptools (version 1.2-4)

approx_areas: Approximate area sizes of the shapes

Description

Approximate the area sizes of the polygons in real-world area units (such as sq km or sq mi), absolute numbers based on the polygon coordinates, proportional numbers, or normalized numbers.

Usage

approx_areas(shp, target = "metric", orig = NA, to = NA,
  total.area = NA, show.warnings = TRUE)

Arguments

shp

shape object, i.e., a SpatialPolygons(DataFrame), or an sf object that can be coerced as such.

target

target unit, one of

"abs":

Absolute numbers based on polygon coordinates.

"prop":

Proportional numbers. In other words, the sum of the area sizes equals one.

"norm":

Normalized numbers. All area sizes are normalized to the largest area, of which the area size equals one.

"metric" (default):

Output area sizes will be either "km" (kilometer) or "m" (meter) depending on the map scale

"imperial":

Output area sizes will be either "mi" (miles) or "ft" (feet) depending on the map scale

other:

Predefined values are "km", "m", "mi", and "ft". Other values can be specified as well, in which case to is required).

These units are the output units. See orig for the coordinate units used by the shape shp.

orig

original unit, i.e. by which the coordinates are defined. By default, the value is taken from the crs projection string defined in shp. Not needed for non-projected shapes, since their areas are determined in another way (see details).

to

multiplier used as follows: orig * to = target. Only needed when orig or target is unknown. For instance, if target is set to "hm" (hectometer), and orig is "m", then to should be 100, meaning 1 hectometer equals 100 meters.

total.area

total area size of shp in number of target units (defined by target). Useful if the total area of the shp differs from a reference total area value. For "metric" and "imperial" units, please provide the total area in squared kilometers respectively miles.

show.warnings

should warnings be shown?

Value

Numeric vector of area sizes. An attribute called unit is added to specify the used target units, which is especially useful when units were set to metric or imperial.

Details

Note that this method is an approximation, since it depends on the used projection and the level of detail of the shape object. Projections with equal-area property are highly recommended. See https://en.wikipedia.org/wiki/List_of_map_projections for equal area world map projections.

For projected shapes, gArea is used, and for unprojected shapes, areaPolygon.

References

Tennekes, M., 2018, tmap: Thematic Maps in R, Journal of Statistical Software, 84(6), 1-39, DOI

See Also

projection_units and approx_distances

Examples

# NOT RUN {
if (require(tmap)) {
    data(NLD_muni)

    NLD_muni$area <- approx_areas(NLD_muni, total.area = 33893)

    tm_shape(NLD_muni) +
        tm_bubbles(size="area", title.size=expression("Area in " * km^2))


    # function that returns min, max, mean and sum of area values
    summary_areas <- function(x) {
        list(min_area=min(x),
             max_area=max(x),
             mean_area=mean(x),
             sum_area=sum(x),
             units=paste0(attr(x, "unit")))
    }

    # area of the polygons
    approx_areas(NLD_muni) %>% summary_areas()

    # area of the polygons, adjusted corrected for a specified total area size
    approx_areas(NLD_muni, total.area=33893) %>% summary_areas()

    # proportional area of the polygons
    approx_areas(NLD_muni, target = "prop") %>% summary_areas()

    # area in squared miles
    approx_areas(NLD_muni, target = "mi") %>% summary_areas()

    # area of the polygons when unprojected
    approx_areas(NLD_muni %>% set_projection(projection="longlat")) %>% summary_areas()
}
# }