sab.areal.interp {AIGIS}R Documentation

Single polygon area-based areal interpolation

Description

Given a single target polygon, a list of zonal polygons, and a matrix of data associated with the zonal polygons, interpolate zonal polygon data to the target polygon. As a wrapper of 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 polygon without having to redo the costly weight-calculating step.

Usage

sab.areal.interp(target, recvar = 1, recvals = bgvals, appdam = FALSE, 
  zones = cabggpc, zbbmat= cabgbbmat, zoneareas = rbgarea, twokcensus = TRUE,
  digits = 6, keepwts = TRUE, dr=damrats, nobounds=FALSE, trimout=TRUE)

Arguments

target A target polygon of class gpc.poly.
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.
appdam CA Wildfire specific. A logical indicating whether or not to apply the empirically derived damage ratio.
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.
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.
keepwts Whether or not to also return the areal weights calculated by arealw. See Value for details.
dr CA Wildfire specific. A vector giving precalculated damage ratios by block group. Only used if appdam=TRUE.
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.
trimout Logical indicating output format if keepwts=TRUE. See Value for details.

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 estimate is generated by assuming any zone less than fully enclosed by the 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 1 by 3 matrix giving the expected value, lower bound and upper bound on enclosed value. The second element is a matrix with the first column indexing those zones with nonzero overlap, and the second column gives those overlaps. This matrix can be passed to dp.interp to generate other interpolated values for the same target polygon.
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, and Anthony Westerling, awesterling@ucmerced.edu

See Also

dp.interp, arealw, mult.arealw

Examples


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

#Calculate structures enclosed by the Cedar fire:
cedar <- sab.areal.interp(fpdemogpc[[3]],recvar=1,appdam=FALSE,keepwts=TRUE)
cedar[[1]]

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

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


[Package AIGIS version 1.0 Index]