tmaptools (version 1.2)

aggregate_map: Aggregate map

Description

Aggregate spatial polygons, spatial lines or raster objects. For spatial polygons and lines, the units will be merged with the by variable. For rasters, the fact parameter determined how many rasters cells are aggregated both horizontally and vertically. Per data variable, an aggregation formula can be specified, by default mean for numeric and modal for categorical varaibles.

Usage

aggregate_map(shp, by = NULL, fact = NULL, agg.fun = NULL, weights = NULL, na.rm = FALSE, ...)

Arguments

shp

shape object, which is one of

1. SpatialPolygons(DataFrame)
2. SpatialLines(DataFrame)
3. SpatialGrid(DataFrame)
4. SpatialPixels(DataFrame)
5. RasterLayer, RasterStack, or RasterBrick
6. sf object if it can be coerced to a Spatial object

by

variable by which polygons or lines are merged. Does not apply to raster objects.

fact

number that specifies how many cells in both horizontal and vertical direction are merged. Only applied to raster objects.

agg.fun

aggregation function(s). One of the following formats:

1. One function (name) by which all variables are aggregated.
2. A vector of two function names called "num" and "cat" that determine the functions by which numeric respectively categorical variables are aggregated. For instance c(num="mean", cat="modal"), which calculates the mean and mode for numeric respectively categorical variables.
3. A list where per variable the (names of the) function(s) are provided. The list names should correspond to the variable names.

These predefined functions can be used: "mean", "modal", "first", and "last".

weights

name of a numeric variable in shp. The values serve as weights for the aggregation function. If provided, these values are passed on as second argument. Works with aggregation functions "mean" and "modal". Use "AREA" for polygon area sizes.

na.rm

passed on to the aggregation function(s) agg.fun.

...

other arguments passed on to the aggregation function(s) agg.fun.

Value

A shape object, in the same format as shp

Details

This function is similar to aggregate from the raster package. However, the aggregation can be specified in more detail: weights can be used (e.g. polygon area sizes). Also, an aggregation function can be specified per variable or raster layer. It is also possible to specify a general function for numeric data and a function for categorical data.

By default, the data is not aggregated. In this case, this function is similar to unionSpatialPolygons from the maptools package. The only difference is way the aggregate-by variable is specified. When using unionSpatialPolygons, the values have to be assigned to IDs whereas when using aggregate_map the data variable name can be assigned to by.

The underlying functions of aggregate_map for Spatial objects are gUnaryUnion, gUnionCascaded, and gLineMerge. For Raster objects, the aggregate is used.

Examples

if (require(tmap)) {
    data(land)

    # original map
    qtm(land, raster="cover_cls")

    ## Not run: 
#     # map decreased by factor 4 for each dimension
#     land4 <- aggregate_map(land, fact=4, agg.fun="modal")
#     qtm(land4, raster="cover_cls")
#     ## End(Not run)

    # map decreased by factor 8, where the variable trees is
    # aggregated with mean, min, and max
    land_trees <- aggregate_map(land, fact=8,
        agg.fun=list(trees="mean", trees="min", trees="max"))

    tm_shape(land_trees) +
    	tm_raster(c("trees.1", "trees.2", "trees.3"), title="Trees (%)") +
    	tm_facets(free.scales=FALSE) +
    	tm_layout(panel.labels = c("mean", "min", "max"))

    data(NLD_muni, NLD_prov)

    # aggregate Dutch municipalities to provinces
    NLD_prov2 <- aggregate_map(NLD_muni, by="province",
        agg.fun = list(population="sum", origin_native="mean", origin_west="mean",
        origin_non_west="mean", name="modal"), weights = "population")

    # see original provinces data
    NLD_prov@data[, c("name", "population", "origin_native", "origin_west", "origin_non_west")]

    # see aggregates data (the last column corresponds to the most populated municipalities)
    NLD_prov2@data

    # largest municipalities in area per province
    aggregate_map(NLD_muni, by="province",
        agg.fun = list(name="modal"), weights = "AREA")@data
}