Rasterise building polygons

Rasterise building polygons (sf_buildings) with reference to population (sf_pop) and/or land use data (sf_landuse), if supplied. Multiple output (a list of) rasters will be generated if building data for multiple years are present.

rasterise_buildings(
  sf_buildings,
  proxy_pop_density = NULL,
  year = NULL,
  sf_pop = NULL,
  sf_landuse = NULL,
  match_buildings_pop = "closest",
  match_buildings_landuse = "closest",
  raster_template = NULL,
  dir_processing = tempdir(),
  dir_export = NULL,
  overwrite = TRUE,
  wopt = list(gdal = c("COMPRESS=LZW")),
  ...
)

Arguments

sf_buildings

sf polygons of the buildings. Data should be in a projected coordinate reference system.

proxy_pop_density

character. Specify column name of the building attribute that is used as an indicator of population density (e.g. building height, no. of levels). This column will be used to assign values to the output raster. If not provided, population density across all building pixels are assumed to be similar.

year

character. Specify column name for the year within sf_buildings, sf_landuse and sf_pop (if provided). Defaults to NULL, assuming that there is no 'year' column. Column data should be numeric.

sf_pop

(optional) sf polygons containing the population census data with column containing the census year. If absent, the output (building rasters) will not be associated with specific population census year(s).

sf_landuse

(optional) sf polygons of the land use zones.

match_buildings_pop

character. Type of matching between sf_buildings and sf_pop (if provided), passed on to match argument in function matchyear(). Either 'exact', 'closest', 'recent' or 'soonest'. Defaults to 'closest'.

match_buildings_landuse

character. Type of matching between sf_buildings and sf_landuse (if provided), passed on to match argument in function matchyear(). Either 'exact', 'closest', 'recent' or 'soonest'. Defaults to 'closest'. This argument is used only if sf_pop is not provided.

raster_template

Either a terra::rast object, or a filepath to the raster used to define the pixel resolution, extent, nrow, ncol of the output raster. Defaults to raster template in tempdir() processed in previous steps. Object is passed to the 'y' argument in terra::rasterize(). Defaults to the template raster generated by the function rasterise_pop() within dir_processing (see next argument).

dir_processing

character. Directory to get intermediate files generated in previous steps (e.g. rasterised population/land use data). Defaults to tempdir().

dir_export

character (optional). File path to directory to export output raster(s) to.

overwrite

logical. Argument passed to terra::writeRaster(). Defaults to TRUE.

wopt

list. Argument passed to terra::writeRaster().

...

Other arguments passed to terra::writeRaster().

Value

List of raster files. Zero values are converted to NA.

Details

If population (sf_pop) and/or land use data (sf_landuse) are supplied, their raster(s) must have been previously generated in the tempdir() using the functions rasterise_pop() and rasterise_landuse(), respectively. Rasterised buildings will be masked away (i.e., convert pixels to NA) at areas with no (zero) population and/or land use data, according to the respective matching year(s). Custom ways to match the years between datasets can be set via the helper function matchyear(). The argument match_buildings_pop provides ways to match each year in the sf_pop (if provided) to a specific year in sf_buildings. Building raster(s) will then be associated with a specific population census year, and removed if there are no matching population census years.

If necessary, the argument match_buildings_landuse provides ways to match each year in sf_buildings with a specific year in sf_landuse, but only if sf_pop is not provided. This is because the main reference point for all the datasets is sf_pop (primary focus is the analysis of population data).

Examples

if (FALSE) {
# load data
data(pop_sgp) # population census block polygons
data(landuse_sgp) # land use polygons


# transform to projected crs
pop_sgp <- sf::st_transform(pop_sgp, sf::st_crs(32648))
landuse_sgp <- sf::st_transform(landuse_sgp, sf::st_crs(32648))


# get osm buildings based on census block polygons (year 2020)
city_boundaries <- pop_sgp %>%
   dplyr::filter(year == 2020) %>%
   sf::st_union() %>%
   sf::st_as_sf() %>%
   smoothr::fill_holes(threshold = units::set_units(1, 'km^2'))  %>% # clean up
   smoothr::drop_crumbs(threshold = units::set_units(1, 'km^2'))  %>%
   sf::st_make_valid()

buildings <- get_buildings_osm(place = city_boundaries,
                               date = as.Date('2021-01-01')) %>%
   mutate(year = 2020)


# run function
buildings_rasters <- rasterise_buildings(buildings,
                                         proxy_pop_density = 'levels',
                                         year = 'year',
                                         sf_pop = pop_sgp,
                                         sf_landuse = landuse_sgp,
                                         match_buildings_pop = 'closest')
}