prep_polygons: Prepare dsmartr polygons

In obrl-soil/dsmartr: dsmartr: An R implementation of the DSMART algorithm

Prepare dsmartr polygons

Description

Prepares soil map inputs for use in dsmartr::iterate().

Usage

prep_polygons(
  src_map = NULL,
  covariates = NULL,
  id_field = NULL,
  sample_method = c("flat", "area_p"),
  sample_rate = NULL,
  rate_floor = NULL,
  rate_ceiling = NULL
)

Arguments

src_map	An sfc_POLYGON/MULTIPOLYGON or SpatialPolygonsDataFrame object representing the soil map to be disaggregated. Format requirements: one row per polygon (data is wide-formatted) A numeric unique ID field for polygons 1-n character columns for soil classes named CLASS_1 to CLASS_n 1-n numeric columns for soil class percentages named PERC_1 to PERC_n. PERC_1 must relate to CLASS_1, etc. Other columns may exist in the object; they will be ignored.
covariates	RasterStack or RasterBrick; environmental covariate datasets.
id_field	String; name of unique identifier field in src_map.
sample_method	String; choice of flat rate per polygon or area-proportional rate.
sample_rate	Integer; Number of samples per polygon.
rate_floor	Integer; desired minimum number of samples per polygon. Optional; used with sample_method = 'area_p'. Defaults to 2x the number of soil classes on a polygon, switch off with samp_floor = 0 (not recommended).
rate_ceiling	Integer; desired maximum number of samples per polygon. Optional; use with sample_method = 'area_p'. Only applies to polygons with a single class component and (effectively) a large area.

Value

A data frame holding polygon input attributes and four new attribute columns:

• area_sqkm: Polygon area in square kilometers, by sf::st_area().

• n_soils: The number of soil classes within the map unit.

• n_samples: The number of environmental covariate point samples that will be taken on each model iteration.

• intersecting_cells: Raster cell index numbers for any cell whose center falls within the polygon boundary.

Outputs are also written to disk.

Note

• The output of this function is a required input for dsmartr::iterate().

• Covariate data should be in a projected CRS with defined units. While the function will run with lat/long data, polygon area calculations may be dangerously inaccurate. Vector inputs will be transformed to match the covariate CRS.

• The intersecting_cells attribute field is a list-column, so the returned object cannot be written to e.g. csv format.

• This function runs faster with a RasterBrick than a Stack.

Examples

## Not run: 
data('heronvale_soilmap')
data('heronvale_covariates')

# flat rate
pr_flat <- prep_polygons(src_map = heronvale_soilmap,
                         covariates = heronvale_covariates,
                         id_field = 'POLY_NO', sample_method = 'flat',
                         sample_rate = 6)

# area_proportional rate with floor
pr_ap <- prep_polygons(src_map = heronvale_soilmap,
                       covariates = heronvale_covariates,
                       id_field = 'POLY_NO', sample_method = 'area_p',
                       sample_rate = 20, rate_floor = 6)

## End(Not run)

obrl-soil/dsmartr documentation built on Feb. 1, 2024, 10:57 p.m.