Spatial wrapper - Generate a set of model domain units for Small Area Estimation (SAE) strategies.

Spatial process to generate a set of model domains (i.e., helper polygons) for Small Area Estimation (SAE) strategies. If helper_autoselect=TRUE, an automated process is used to select helper polygons within a large area overlapping the small area. The helper polygons are unioned with the small area polygons, resulting in a set of model domains that can be used for SAE.

Usage

spGetSAdoms(
  smallbnd,
  smallbnd_dsn = NULL,
  smallbnd.unique = NULL,
  smallbnd.domain = NULL,
  smallbnd.filter = NULL,
  smallbnd.stfilter = NULL,
  helperbnd = NULL,
  helperbnd_dsn = NULL,
  helperbnd.unique = NULL,
  helperbnd.filter = NULL,
  largebnd = NULL,
  largebnd_dsn = NULL,
  largebnd.unique = NULL,
  largebnd.filter = NULL,
  maxbnd = NULL,
  maxbnd_dsn = NULL,
  maxbnd.unique = NULL,
  maxbnd.filter = NULL,
  helper_autoselect = TRUE,
  nbrdom.min = NULL,
  maxbnd.threshold = 10,
  largebnd.threshold = 5,
  multiSAdoms = FALSE,
  bayes = FALSE,
  showsteps = TRUE,
  savedata = FALSE,
  savesteps = FALSE,
  saveobj = FALSE,
  objnm = "SAdomdat",
  maxbnd.addtext = TRUE,
  largebnd.addtext = FALSE,
  savedata_opts = NULL,
  addstate = FALSE,
  dissolve = FALSE,
  byeach = TRUE,
  modelbyeach = FALSE
)

Arguments

smallbnd: sf R object or String. Small area of interest boundary. Can be a spatial polygon object, full pathname to a shapefile, or name of a layer within a database.
smallbnd_dsn: String. Data source name (dsn; e.g., sqlite or shapefile pathname) of smallbnd. The dsn varies by driver. See gdal OGR vector formats (https://www.gdal.org/ogr_formats.html). Optional if smallbnd is an R object.
smallbnd.unique: String. The attribute in smallbnd that defines unique domain identifier in smallbnd that defines the unique small area(s). If NULL, an attribute is appended to smallbnd attribute table and used as smallbnd.unique, defining one polygon (SMALLAREA="SMALLAREA").
smallbnd.domain: String. A different attribute to use as for grouped modeling domains (optional). If NULL, smallbnd.domain=smallbnd.unique.
smallbnd.filter: String. A filter for smallbnd. Must be R syntax.
smallbnd.stfilter: String. A spatial filter for smallbnd to include only smallbnd polygons that intersect (or overlap >= 30 boundary. The filter is based on the stunitco internal R object, with attributes: STATECD, STATENM, UNITCD, UNITNM, COUNTYCD, COUNTYNM. The filter should include one of these attributes and must be R syntax.
helperbnd: sf R object or String. Name of polygon spatial layer delineating helper polygons for small area models. Can be a spatial polygon object, full pathname to a shapefile, or name of a layer within a database.
helperbnd_dsn: String. Data source name (dsn; e.g., sqlite or shapefile pathname) of helperbnd. The dsn varies by driver. See gdal OGR vector formats (https://www.gdal.org/ogr_formats.html). Optional if helperbnd is an R object.
helperbnd.unique: String. The attribute in helper polygon layer that defines unique helper polygons.
helperbnd.filter: String. A filter for helperbnd. Must be R syntax.
largebnd: sf R object or String. Name of large area polygon spatial layer, defining the model data extent for building small are models. Can be a spatial polygon object, full pathname to a shapefile, or name of a layer within a database.
largebnd_dsn: String. Data source name (dsn; e.g., sqlite or shapefile pathname) of largebnd. The dsn varies by driver. See gdal OGR vector formats (https://www.gdal.org/ogr_formats.html). Optional if largebnd is an R object.
largebnd.unique: String. The attribute in largebnd polygon layer that defines unique large area polygon(s).
largebnd.filter: String. A filter for largebnd. Must be R syntax.
maxbnd: sf R object or String. Name of polygon spatial layer, defining the maximum model data restraint for adding more helper polygons for building small are models. Can be a spatial polygon object, full pathname to a shapefile, or name of a layer within a database.
maxbnd_dsn: String. Data source name (dsn; e.g., sqlite or shapefile pathname) of maxbnd. The dsn varies by driver. See gdal OGR vector formats (https://www.gdal.org/ogr_formats.html). Optional if maxbnd is an R object.
maxbnd.unique: String. The attribute in maxbnd polygon layer that defines unique max restraint area(s).
maxbnd.filter: String. A filter for maxbnd. Must be R syntax.
helper_autoselect: Logical. If TRUE, the helper boundaries are automatically selected based on intersection with maxbnd and/or largebnd and number of helperbnds defined by nbrdom.min.
nbrdom.min: Integer. Set number for minimum domains for modeling. If NULL, all domains within largebnd are selected.
maxbnd.threshold: Integer. Percent for including additional maxbnds for selecting helperbnds. If multiSAdoms=FALSE, the maxbnd with greatest percentage over the maxbnd.threshold is selected.
largebnd.threshold: Integer. Percent for including additional largebnds for selecting helperbnds.
multiSAdoms: Logical. If TRUE, and the percent intersect of smallbnd with maxbnd is greater than maxbnd.threshold, more than 1 SAdoms will be output in list.
bayes: Logical. If TRUE, does not union smallbnd with largebnd. If multiSAdoms = TRUE, returns intersecting maxbnd where larger than maxbnd threshold.
showsteps: Logical. If TRUE, intermediate steps of selection process are displayed.
savedata: Logical. If TRUE, save SAdoms spatial layer to outfolder.
savesteps: Logical. If TRUE, save steps spatial intermediate layers and JPG images. All spatial layers are output as *.shp format in a separate folder (SAdoms_steps).
saveobj: Logical. If TRUE, save SAdomdat object to outfolder.
objnm: String. Name of *.rds object.
maxbnd.addtext: Logical. If TRUE, adds text to intermediate step plots for maxbnd displays.
largebnd.addtext: Logical. If TRUE, adds text to intermediate step plots for largebnd displays.
savedata_opts: List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE.
addstate: Logical. If TRUE, appends state attribute to SAdoms.
dissolve: Logical. If TRUE, aggregates polygons to smallbnd.domain or smallbnd.unique.
byeach: Logical. If TRUE, an estimate is desired for each smallbnd domain. If FALSE, all smallbnd domains are aggregates one SAdom (DOMAIN = 1).
modelbyeach: Logical. If TRUE, creates an SAdom for each smallbnd polygon.

Value

SAdomslst: List object. Set(s) of model domain units. If multiSAdoms=TRUE, the list may have more than one set of model domain units.
smallbndlst: List object. smallbnd(s). If multiSAdoms=TRUE, the list may have more than one set of smallbnd.

If exportsp=TRUE, the SAdoms spatial object(s) is exported to outfolder, with format specified by out_fmt.

Details

optional boundaries

The helperbnd, largebnd, and maxbnd are optional. If helperbnd=NULL, the smallbnd polygons are used for model domain units. If largebnd=NULL, the maxbnd is used to define the large area. If maxbnd=NULL, the largebnd is used to restrain the model extent. If both, largebnd=NULL and maxbnd=NULL, the extent of the smallbnd or helperbnd is used for defining and restraining the model extent.

nbrdom.min

The number of helper polygons selected are defined by nbrdom.min parameter. If nbrdom.min=NULL, all helper polygons within the large area extent are selected.

multiSAdoms

Use multiSAdoms parameter when small area of interest has multiple polygon features and the small area polygons overlap (within maxbnd.threshold) more than one maxbnd polygon. If multiSAdoms=TRUE, more than one set of model domain units are generated; one for each maxbnd where overlap is within maxbnd.threshold. If multiSAdoms=FALSE, only one set of model domain units are generated, using the maxbnd with the greatest overlap.

AOI attribute

A variable named 'AOI' is appended to the SAdoms attribute table to distinguish between the small area of interest polygons and the helper domain units.

Note

If exportsp=TRUE and out_fmt="shp":
The st_write (sf) function is called. The ArcGIS driver truncates variable names to 10 characters or less. Variable names are changed before export using an internal function (trunc10shp). If Spatial object has more than 1 record, it will be returned but not exported.

The spTransform (sf) method is used for on-the-fly map projection conversion and datum transformation using PROJ.4 arguments. Datum transformation only occurs if the +datum tag is present in the both the from and to PROJ.4 strings. The +towgs84 tag is used when no datum transformation is needed. PROJ.4 transformations assume NAD83 and WGS84 are identical unless other transformation parameters are specified. Be aware, providing inaccurate or incomplete CRS information may lead to erroneous data shifts when reprojecting. See spTransform help documentation for more details.

Author

Tracey S. Frescino