ab.areal.interp {AIGIS}R Documentation

Area-based areal interpolation for multiple polygons

Description

Given a list of target polygons, a list of zonal polygons, and a matrix of data associated with the zonal polygons, interpolate zonal polygon data to specified target polygons. As a wrapper of mult.arealw and dp.interp, it generates areal weights as an intermediate product, which can also be returned if desired. This allows other variables in the data record to be interpolated to the same polygons without having to redo the costly weight-calculating step.

Usage

ab.areal.interp(target.ind = "all", targetlist = firepgpc, trim = TRUE, 
  recvar = 1, recvals = bgvals, zones = cabggpc, zbbmat = cabgbbmat, 
  zoneareas = rbgarea, appdam = TRUE, dr = damrats, twokcensus = TRUE, 
  digits = 6, nobounds = FALSE, keepwts = TRUE, verbose = 2)

Arguments

target.ind A vector containing list indices of target polygons, or character “all”, which indicates the entire list is to be used.
targetlist A list of possible target polygons
trim A logical indicating whether areal weights should be stored compactly or in one long vector per target polygon. The default is TRUE, as for lengthy lists of target polygons available memory can become prohibitive.
recvar An integer indicating which column of the record value matrix to use. That is, what variable is to be interpolated.
recvals A matrix of record values containing the data to be interpolated, with rows corresponding to zones, and columns corresponding to different variables.
zones List of zonal polygons from which data will be interpolated to the target.
zbbmat “Zonal bounding box matrix.” Either a matrix of dimension length(zones) by 4, or character “none”. If “none,” an appropriate matrix is automatically computed by a call to bbox.mat. See ‘Details.’
zoneareas A vector giving the area of each zone or character “none”, indicating they must be calculated inside the function.
appdam CA Wildfire specific. A logical indicating whether or not to apply the empirically derived damage ratio.
dr CA Wildfire specific. A vector giving precalculated damage ratios by block group. Only used if appdam=TRUE.
twokcensus Logical indicating whether the data in question is block group level data for California from the 2000 US Census. If ‘TRUE’, the function automatically handles certain ideosyncracies associated with that data.
digits Digits argument passed to round internally. Used in setting the tolerance for considering fractional overlap to be 100 percent. Due to numerical issues, overlap will not always be identically 1 when a zone is contained entirely within the target. There should be little reason to modify this away from the default value of six.
nobounds Logical indicating whether or not to return the estimates without bounds. Default is ‘FALSE’, but there may be situations where having no bounds will be more convenient for handling data objects. See Details for how the bounds are generated.
keepwts Whether or not to also return the areal weights calculated by arealw. See Value for details.
verbose An integer indicating how frequently to print progress through the target polygons. Will print a message every time 10 to the verbose power polygons have been processed. Setting verbose negative results in no progress output.

Details

If not “none”, ‘zbbmat’ must take the form of a length(zones) by 4 matrix, where each row corresponds to the bounding latitude and longitude values for polygons in zones, the same format returned by the function bbox.mat. The columns correspond to low longitude, high longitude, low latitude and high latitude respectively.

The lower bound estimates are generated by assuming any zone less than fully enclosed by the current target polygon contributes zero to the total value contained. The upper bound is generated by assuming that any zone with nonzero overlap contributes its entire value. In all cases, zones that are entirely enclosed contribute their entire value.

Value

The output under default settings is a list of two elements. The first element is a length(target.ind) by 3 matrix giving the expected value, lower bound and upper bound on enclosed value, for each target polygon specified. The second element is another list, each entry of which has the matrix of areal weights for the corresponding target polygon. In these matrices, the first column indexes those zones with nonzero overlap, and the second column gives those overlaps. These matrices can be passed to dp.interp to generate other interpolated values for the same target polygon, either individually, or using lapply.
If nobounds=TRUE, lower and upper bound are not returned, and the result is just a vector of length one.
If keepwts=FALSE, the function returns only the matrix or vector as above, and the areal weights are not returned.
If trimout=FALSE, the weights are returned as a vector of length equal to nrow(recvals), rather than as a matrix containing specifying only those nonzero weights. See help for arealw for more info.
Thus, there can be six different possible output forms. The default should suffice in most cases.

Note

The bounds on the outputs when appdam is set to TRUE do not take into account uncertainty in the damage ratio. The absolute high would be to take the upper bound when not applying the damage ratio, and the absolute low is always zero.

Author(s)

Benjamin P. Bryant, bryant@prgs.edu

Examples


data(bgvals)
data(cabgbbmat)
data(cabggpc)
data(damrats)
data(fpdemogpc)
data(rbgarea)
data(polytobg)

#Calculate structures enclosed by the Union and Cedar fires:
cedar <- ab.areal.interp(target.ind=c(1,3),targetlist=fpdemogpc,recvar=1,
  appdam=FALSE,keepwts=TRUE)
  
#check it out:
cedar[[1]]

#Using the weights already generated, calculate the total value enclosed for
#the Cedar fire:
dp.interp(cedar[[2]][[2]],recvar=2,appdam=FALSE,trimmedin=TRUE)

#Again using the weights already generated, calculate estimated houses
#destroyed, this time for both at the same time:
lapply(cedar[[2]],dp.interp,recvar=1,appdam=TRUE,trimmedin=TRUE)


[Package AIGIS version 1.0 Index]