calculate_footstats: Feature statistics of building footprints

Source: R/calculate_footstats.R

Calculate groups of metrics for building footprint datasets

calculate_footstats(
  X,
  zone = NULL,
  what = "all",
  how = NULL,
  controlZone = list(zoneName = "zoneID", method = "centroid"),
  controlUnits = list(areaUnit = "m^2", perimUnit = "m", distUnit = "m"),
  controlDist = list(maxSearch = 100, method = "centroid", unit =
    controlUnits$distUnit),
  filter = list(minArea = NULL, maxArea = NULL),
  verbose = TRUE
)

# S3 method for sf
calculate_footstats(
  X,
  zone = NULL,
  what = "all",
  how = NULL,
  controlZone = list(zoneName = "zoneID", method = "centroid"),
  controlUnits = list(areaUnit = "m^2", perimUnit = "m", distUnit = "m"),
  controlDist = list(maxSearch = 100, method = "centroid", unit =
    controlUnits$distUnit),
  filter = list(minArea = NULL, maxArea = NULL),
  verbose = TRUE
)

# S3 method for sfc
calculate_footstats(
  X,
  zone = NULL,
  what = "all",
  how = NULL,
  controlZone = list(zoneName = "zoneID", method = "centroid"),
  controlUnits = list(areaUnit = "m^2", perimUnit = "m", distUnit = "m"),
  controlDist = list(maxSearch = 100, method = "centroid", unit =
    controlUnits$distUnit),
  filter = list(minArea = NULL, maxArea = NULL),
  verbose = TRUE
)

# S3 method for sp
calculate_footstats(
  X,
  zone = NULL,
  what = "all",
  how = NULL,
  controlZone = list(zoneName = "zoneID", method = "centroid"),
  controlUnits = list(areaUnit = "m^2", perimUnit = "m", distUnit = "m"),
  controlDist = list(maxSearch = 100, method = "centroid", unit =
    controlUnits$distUnit),
  filter = list(minArea = NULL, maxArea = NULL),
  verbose = TRUE
)

# S3 method for character
calculate_footstats(
  X,
  zone = NULL,
  what = "all",
  how = NULL,
  controlZone = list(zoneName = "zoneID", method = "centroid"),
  controlUnits = list(areaUnit = "m^2", perimUnit = "m", distUnit = "m"),
  controlDist = list(maxSearch = 100, method = "centroid", unit =
    controlUnits$distUnit),
  filter = list(minArea = NULL, maxArea = NULL),
  verbose = TRUE
)

Arguments

X

object with building footprint polygons. This argument can take multiple spatial types, including sf and sp, or a filepath string to a file.
zone

A spatial polygon file defining areas. Or a string identifying a column within X which provides a zonal index for summarising values. Alternatively a vector of indices (with length(index)==nrow(X)) can be provided. If omitted, all observations in X are assumed to be within one zone.
what

list of strings naming the columns or built-in geometry measures to calculate for each footprint. Other options include 'all' or 'nodist' to calculate all available characteristics and all except nearest-neighbour distance metrics.
how

list of strings naming functions to be used to calculate summary statistics. The functions can be built-in functions (e.g. "mean","sd"), or user-defined function names.
controlZone

(optional) named list. Setting controls passed on to zonalIndex. Elements can include zoneName and method.
controlUnits

(optional) named list. Elements can include areaUnit, perimUnit, and distUnit. The values for these items should be strings that can be coerced into a units object.
controlDist

(optional) named list to override default options for distance calculations. Elements can include maxSearch and method. Ignored if metrics does not include a distance calculation. See fs_nndist.
filter

(optional) named list with minArea and maxArea. These are numeric values to filter footprints prior to processing. Default values are NULL and do not filter any records.
verbose

logical. Should progress messages be printed. Default TRUE.

Value

a data.table with an index column identifying the zones and named columns for each footprint summary statistic.

Details

calculate_footstats

calculate_footstats is a wrapper function combining several internal functions from foot. It can calculate various geometric measures for each footprint polygon, including area, perimeter, compactness, shape, angle of rotation, and nearest neighbour distance. To find the list of built-in characteristics and summary metrics, use list_fs().

The what and how arguments are lists specifying the characteristics and the summary metrics to calculated, respectively. Each "how" function will be applied to each "what" characteristic. To apply a metric to only a subset of characteristics, nested lists, with groups of characteristics and functions can be supplied. See examples.

The control arguments are sets of lists with named arguments that pass on these parameters to other foot functions. These are optional.

See also

zonalIndex, fs_nndist, list_fs

Examples

data("kampala", package="foot")
buildings <- kampala$buildings
adminzones <- kampala$adminZones

# no summary statistics, just geometry calculations
calculate_footstats(buildings, adminzones, what=list("area","perimeter"))

#> Selecting metrics 
#> Setting control values. 
#> Pre-calculating areas 
#> Pre-calculating perimeters 
#> Creating zonal index 
#> No summary functions found, returning metrics. 
#> 
#>                   area     perimeter
#>    1:  561.75263 [m^2] 121.55839 [m]
#>    2:   56.68961 [m^2]  31.20118 [m]
#>    3:   56.09613 [m^2]  34.11899 [m]
#>    4: 2303.88560 [m^2] 220.13423 [m]
#>    5:  230.29461 [m^2]  60.57280 [m]
#>   ---                               
#> 4836:   75.84167 [m^2]  35.91359 [m]
#> 4837:   53.84585 [m^2]  31.22369 [m]
#> 4838:   69.88213 [m^2]  33.72564 [m]
#> 4839:  377.77398 [m^2]  99.95716 [m]
#> 4840:  165.67331 [m^2]  53.28785 [m]

# average building footprint area
calculate_footstats(buildings, 
                    zone=adminzones, 
                    what="area", how="mean")

#> Selecting metrics 
#> Setting control values. 
#> Pre-calculating areas 
#> Creating zonal index 
#> 
#> Calculating  1  metrics ... 
#>    area mean  
#> Finished calculating metrics. 
#>     zoneID        area_mean
#>  1:      1  404.40622 [m^2]
#>  2:      2  212.00113 [m^2]
#>  3:      3  527.43250 [m^2]
#>  4:      4  557.58574 [m^2]
#>  5:      5  571.26921 [m^2]
#>  6:      6 1026.54193 [m^2]
#>  7:      7 2036.80923 [m^2]
#>  8:      8  912.32644 [m^2]
#>  9:      9  182.49803 [m^2]
#> 10:     10  253.12878 [m^2]
#> 11:     11  221.10092 [m^2]
#> 12:     12   86.77135 [m^2]
#> 13:     13  664.58989 [m^2]
#> 14:     14   82.22200 [m^2]
#> 15:     15   81.14808 [m^2]
#> 16:     16   69.06033 [m^2]
#> 17:     17  139.80020 [m^2]
#> 18:     18   87.40828 [m^2]
#> 19:     19  238.14083 [m^2]
#> 20:     20  200.28897 [m^2]
#> 21:     21  245.19516 [m^2]
#> 22:     22  193.25951 [m^2]
#> 23:     23  774.81871 [m^2]
#> 24:     24  220.25691 [m^2]
#> 25:     25  508.49467 [m^2]
#> 26:     26 1169.63732 [m^2]
#> 27:     27  191.91348 [m^2]
#> 28:     29  239.83238 [m^2]
#> 29:     30  204.59597 [m^2]
#> 30:     31  142.77472 [m^2]
#> 31:     32  273.99468 [m^2]
#> 32:     33  420.54389 [m^2]
#> 33:     34  177.61130 [m^2]
#>     zoneID        area_mean
                    
# calculate multiple metrics - nested lists to group arguments
calculate_footstats(buildings, adminzones, 
                    what=list(list("area"), list("perimeter")), 
                    how=list(list("mean","sum"), list("sd","cv")))

#> Selecting metrics 
#> Setting control values. 
#> Pre-calculating areas 
#> Pre-calculating perimeters 
#> Creating zonal index 
#> 
#> Calculating  4  metrics ... 
#>    area mean  
#>    area sum  
#>    perimeter sd  
#>    perimeter cv  
#> Finished calculating metrics. 
#>     zoneID        area_mean          area_sum perimeter_sd perimeter_cv
#>  1:      1  404.40622 [m^2]   8492.5307 [m^2]    55.665551    0.6561304
#>  2:      2  212.00113 [m^2]  29892.1595 [m^2]    44.587096    0.7313348
#>  3:      3  527.43250 [m^2]  25844.1923 [m^2]    88.397185    0.9811076
#>  4:      4  557.58574 [m^2]  64122.3606 [m^2]    88.872380    1.0600954
#>  5:      5  571.26921 [m^2]  26849.6529 [m^2]    88.251084    0.9581201
#>  6:      6 1026.54193 [m^2]  35928.9675 [m^2]   105.385333    0.9616081
#>  7:      7 2036.80923 [m^2]  28515.3292 [m^2]   170.141093    0.9286094
#>  8:      8  912.32644 [m^2]  44703.9953 [m^2]   109.992947    0.8489816
#>  9:      9  182.49803 [m^2]  48361.9770 [m^2]    54.922117    0.9246860
#> 10:     10  253.12878 [m^2]   7593.8634 [m^2]    75.861771    1.0900293
#> 11:     11  221.10092 [m^2]  24321.1016 [m^2]    61.492800    0.8815988
#> 12:     12   86.77135 [m^2]   3123.7687 [m^2]    28.289807    0.7257624
#> 13:     13  664.58989 [m^2]   2658.3596 [m^2]   139.514757    1.3165558
#> 14:     14   82.22200 [m^2]   6742.2042 [m^2]     7.755949    0.2059276
#> 15:     15   81.14808 [m^2]  19313.2428 [m^2]    18.498145    0.5073846
#> 16:     16   69.06033 [m^2]   9944.6881 [m^2]    10.681959    0.3095971
#> 17:     17  139.80020 [m^2]  14818.8207 [m^2]    27.254588    0.5541695
#> 18:     18   87.40828 [m^2]  37061.1108 [m^2]    26.337404    0.7093738
#> 19:     19  238.14083 [m^2]  96923.3173 [m^2]    26.881426    0.4151437
#> 20:     20  200.28897 [m^2]  80716.4561 [m^2]    30.741879    0.5257108
#> 21:     21  245.19516 [m^2]  18144.4417 [m^2]    46.479887    0.7810948
#> 22:     22  193.25951 [m^2]  10242.7539 [m^2]    12.929421    0.2238327
#> 23:     23  774.81871 [m^2] 133268.8176 [m^2]   113.778927    1.1205392
#> 24:     24  220.25691 [m^2]  62112.4473 [m^2]    33.388278    0.5317242
#> 25:     25  508.49467 [m^2]  11695.3775 [m^2]    84.106005    0.8940386
#> 26:     26 1169.63732 [m^2] 150883.2148 [m^2]   146.936669    1.0767096
#> 27:     27  191.91348 [m^2]  33968.6861 [m^2]    25.259149    0.4462858
#> 28:     29  239.83238 [m^2]  37174.0182 [m^2]    63.489927    1.0713172
#> 29:     30  204.59597 [m^2]  15344.6975 [m^2]    33.438265    0.5426390
#> 30:     31  142.77472 [m^2]    142.7747 [m^2]           NA           NA
#> 31:     32  273.99468 [m^2]  35893.3028 [m^2]    45.074544    0.6469339
#> 32:     33  420.54389 [m^2]   7149.2461 [m^2]    55.919761    0.6104610
#> 33:     34  177.61130 [m^2] 147594.9907 [m^2]    42.933274    0.7474269
#>     zoneID        area_mean          area_sum perimeter_sd perimeter_cv