Gives every location in the study area to its nearest input point, so
each point gets one cell. Use it when the observations themselves define
the cells (sampling sites, monitoring stations, service points): cell size
then follows sampling density, with small cells where the points are dense
and large ones where they are sparse. Use create_grid_polygons() instead
for equal-area cells, or for a resolution that does not depend on where
the data are.
Usage
create_voronoi_polygons(
points_sf,
boundary = NULL,
expand = 0,
clip = TRUE,
keep_duplicates = FALSE,
crs = NULL,
quiet = FALSE,
cover = NULL
)Arguments
- points_sf
An sf object with POINT/MULTIPOINT geometries. Points with no CRS whose coordinates look like lon/lat (the heuristic
ensure_projected()applies, with its warning) are taken as EPSG:4326 and projected, as lon/lat points are. Points that mix XY and XYZ (or XYM), or that carry M, are read in x and y, since sf reads a layer in the dimension of its first geometry and GEOS refuses M; the attributes the seeding functions set on them are kept.- boundary
Optional polygonal sf object. When exactly one of
points_sfandboundaryhas a CRS, the other is interpreted in it, with a warning. CRS-less points, and a CRS-less boundary given with projected points, are read asharmonize_crs()does (lon/lat-looking coordinates are reprojected from EPSG:4326, others are stamped); CRS-less points that do not look like lon/lat cannot take a geographic boundary's CRS, and are refused with an error. A CRS-less boundary given with lon/lat points (or with CRS-less points taken as lon/lat) is read as lon/lat when its coordinates fit the lon/lat envelope, and refused with an error otherwise. Rows without a location, rows the repair leaves without a polygon, vertices at a latitude beyond 90 and mixed dimensions are handled as "Boundaries" in spatialkit-geometry says.- expand
Numeric; absolute distance, in the working CRS's units, by which the boundary (or the hull derived from the points) is grown before the diagram is built. With
clip = TRUEthe cells are clipped to the grown boundary, so they reachexpandbeyond the study area, and a point up toexpandoutside it gets a cell and anindexvalue. The grown boundary is the one returned asboundary.- clip
Logical; clip the cells to the boundary. Default
TRUE.- keep_duplicates
Logical. With
FALSE(the default), points are merged before the diagram is built when they round to one point in coordinates centred on the middle of their bounding box, divided by its diagonal and rounded to 2^-30 of it, so points within about a billionth of the extent of each other count as coincident in any unit or origin and share one cell. WithTRUEonly points at exactly one location are merged. Every point is indexed to the cell that holds it.- crs
Optional target CRS: anything
sf::st_crs()accepts, including an sf or sfc layer, whose CRS is used. A projected CRS is the working CRS. A geographic one (EPSG:4326, say) is the CRS the result is returned in: the cells are built in the local projected CRSensure_projected()picks for the points, so they are nearest-point cells on the ground, and are then transformed, with long edges densified. Seeds that are the centres a profile scored are built in the CRS the profile worked in instead (see "Seeds a profile scored"). Where four seeds stand the same distance from one point, as on gridded locations, two cells can meet there at two corners that differ only by rounding, which the transform to degrees can put at one point, and sf's spherical engine (s2) refuses such a cell.assign_features_to_polygons()joins the cells of the centres a profile scored in the CRS they were built in, while they carry the record that says so (scored_cells = TRUE).sf::st_area()andsf::st_union()stop on such a cell in degrees with s2's error. The package's other joins and measures of it stop with an error of class"spatialkit_cells_degenerate"("Polygons in degrees" in spatialkit-geometry gives the exceptions). Transform the cells to a projected CRS first.- quiet
Logical; suppress this function's progress
message()s. It does not silence R warnings, nor the package's console log echo (seespatialkit_quietfor that). DefaultFALSE.- cover
Optional sf or sfc layer the cells have to hold, read when there is no
boundary: the observations (points), or a polygon. The boundary is then derived from it instead of frompoints_sf: the convex hull of the cover's points, or its polygons, grown by 2 percent of the diagonal. This is what seeds need, because seeds lie inside the data they stand for and their own hull stops short of it (see "Details"). WhenNULL, the cover the seeding functions attach is used (attr(points_sf, "cover"), set byget_voronoi_seeds(),voronoi_seeds_kmeans()andvoronoi_seeds_random()). A cover with no CRS is read in the coordinates ofpoints_sf, and one in another CRS is transformed. A generator outside the cover keeps its ground (the hull of the generators is added); a cover that holds none of the generators is set aside with a warning. With aboundary, the boundary sets the cells andcoveris only checked against them: the number of its points that fall outside every cell is returned asparams$cover_outside, with a warning of class"spatialkit_unassigned"when it is not 0 (a polygon cover is not checked). A cover, given or attached, that mixes XY and XYZ (or XYM) geometries, or that carries M, is read in x and y. A row of the cover with a coordinate that is not finite or lies beyond 1e150, read as given before any move, is read as an empty row.
Value
A list with these elements:
cellsThe cells, one polygon per unique point, with a stable
cell_id.indexOne
cell_idper row ofpoints_sf, andNAfor a point that falls outside every cell: outside the study area (grown byexpandwhen it is positive), and farther than a thousandth of the median cell width from the nearest cell, so a summary built from it counts only the points the tessellation covers. Such points are counted inparams$n_outside, and a warning of class"spatialkit_unassigned"gives their number. For seeds (see "Details")indexholds the cell each seed generates, whether the seed lies inside the boundary or not, andNAonly for a seed whose cell the clip removed whole or without a location (an empty geometry, or a coordinate that is not finite or lies beyond 1e150);params$n_outsidecounts those, the warning names them as seeds, andparams$snappedlists only the seeds whose entry is the cell they were snapped to.boundaryThe boundary the cells were built in: the one supplied or derived, grown by
expand.method"voronoi".paramsThe settings and diagnostics of the build, among them:
boundary_source: where the boundary came from,"boundary"(the argument),"cover"(thecoverargument),"seeds' cover"(the cover attached topoints_sf) or"points"(the hull ofpoints_sfitself);cover_outside: the number ofcoverpoints outside every cell when a pointcoverwas given with aboundary, andNULLotherwise;partition: present whenpoints_sfis a layer of seeds that records the kind of partition that placed it (attr(points_sf, "partition"), seeget_voronoi_seeds()), the same list, so the cells say what built them. Seeds of plain k-means record nothing, andparamsthen has no such element; neither has it for points that are not seeds;count_rule: present whenpoints_sfcarries the record of how its count was set (attr(points_sf, "count_rule"): the seeds of aselect_resolution()result, or seeds a seeding function placed from one), the same list, withscored_cells = FALSEwhen the seeds are fewer or more than its count. The cells carry it too, asattr(cells, "count_rule");assign_features_to_polygons()copies it to the rows it assigns, andsummarize_by_cell()checks its result against it.
Details
sf::st_voronoi() builds the diagram. This function projects lon/lat
input, builds and buffers an envelope so edge cells are bounded, clips to
boundary, restores the point-to-cell correspondence that st_voronoi()
scrambles, and numbers the cells with stable cell_id values.
The generators are the points' vertices, not the features. A MULTIPOINT
feature with several vertices therefore gets one cell per vertex, and its
index entry is the smallest cell_id among the cells it touches; the
others are referenced by no feature. Other functions in the package
(prep_model_data(), make_folds()) reduce such a feature to its
centroid instead, so cast to POINT, or take centroids, first if one cell
per feature is what you want.
With no boundary the cells are clipped to a boundary derived from the
data. For observations that is their own convex hull grown by 2 percent of
its diagonal, so every observation has a cell. Seeds are different: k-means
centres, random points in a study area and the centres a resolution
profile scored all lie inside the ground they stand for, and cells clipped
to the hull of the seeds leave the edge of that ground uncovered. The
boundary is therefore derived from the cover when
there is one: the argument, or the cover the seeding functions attach to
their result. A layer that looks like seeds and has neither a boundary nor
a cover (seeds bound with rbind(), which drops the attribute, or built
by hand) gets the seeds' own hull and a warning of class
"spatialkit_no_cover".
A seed stands for its cell, so index gives each seed the cell it
generates. A k-means seed is a mean of observations and can lie outside a
boundary that is not convex, in a bay or a bend of a coast (see
get_voronoi_seeds()). Its cell, the part of the study area nearer it
than any other seed, is built, and its index entry is that cell's
cell_id, although the seed lies in no cell. A seed is NA only when
every part of the study area is nearer another seed, so the clip removed
its cell whole, or when it has no location (its geometry is empty, or a
coordinate is not finite or lies beyond 1e150). The points are seeds when
a seeding function returned them (get_voronoi_seeds(),
voronoi_seeds_kmeans(), voronoi_seeds_random(), rbind() of such
layers included), when they are the seeds of a select_resolution()
result, and when a cover is passed with them. A selection's seeds are
seeds by the attributes they carry, which rbind() and a write to a file
drop. Any other points are indexed by the cell that holds them, so a
point outside the study area is NA, unless it lies within a thousandth
of the median cell width of a cell, whose ID it then takes (see index
in build_tessellation()); that includes observations that
carry a selection's record of the count, as
assign_features_to_polygons() returns them. Seeds placed by hand, and
a selection's seeds that lost their attributes, are seeds once they pass
through get_voronoi_seeds(method = "provided", seeds = ).
Seeds a profile scored
The seeds of a select_resolution() result, and the seeds
get_voronoi_seeds() or voronoi_seeds_kmeans() return for one, are the
centres resolution_profile() scored, and their record of the count
(attr(, "count_rule")) says so (scored_cells = TRUE) and holds the
centres in the CRS the profile worked in. (On a profile without an
estimate fitted to a subsample the seeds are those centres refitted to
every point, which carry attr(, "refit"); their record says
scored_cells = FALSE, and their cells are built as other seeds' are.
So are seeds fewer or more than the record's count, such as a
selection's seeds cut down to some of its rows: they are not the centres
the profile scored, and their record is handed on with
scored_cells = FALSE, as get_voronoi_seeds() (method = "provided")
marks such seeds.)
Unless a projected crs is
given, their cells are built in that CRS, whatever CRS the seeds arrive
in (degrees, or the CRS of a boundary they were placed in), and returned
in it, or in a geographic crs when one is given. When the seeds are
those centres (as many, each at a different centre, within a thousandth
of its distance from the next nearest), each is first put at its centre
as the record holds it, so rounding the seeds took on in another CRS
does not move an edge. The cells are then the cells each row was scored
in, and assign_features_to_polygons() gives a point on an edge between
two of them the cell the profile scored it in.
Points far from the origin of their CRS
Points so far from the origin of their CRS that doubles there are spaced
more than a millionth of their extent apart (0.125 at 1e15, beside a layer
a few kilometres across) have the cells' edges and their own cells read
at that rounding, so two points that close can fall in one cell. The
cells are built, and a warning of class "spatialkit_xy_imprecise"
gives the spacing and the extent.
Examples
library(sf)
set.seed(1)
pts <- st_as_sf(
data.frame(x = 5e5 + runif(15, 0, 100), y = 5e6 + runif(15, 0, 100)),
coords = c("x", "y"), crs = 32632
)
res <- create_voronoi_polygons(pts, quiet = TRUE)
res$cells # one polygon per unique point, with stable cell_id
#> Simple feature collection with 15 features and 1 field
#> Geometry type: POLYGON
#> Dimension: XY
#> Bounding box: xmin: 500003.5 ymin: 4999999 xmax: 500097.1 ymax: 5000102
#> Projected CRS: WGS 84 / UTM zone 32N
#> First 10 features:
#> geometry cell_id
#> 1 POLYGON ((500024.2 5000020,... 1
#> 2 POLYGON ((500030.5 5000080,... 2
#> 3 POLYGON ((500007.1 5000040,... 3
#> 4 POLYGON ((500024.2 5000020,... 4
#> 5 POLYGON ((500048.1 5000053,... 5
#> 6 POLYGON ((500025 5000064, 5... 6
#> 7 POLYGON ((500055.9 5000081,... 7
#> 8 POLYGON ((500037.4 5000019,... 8
#> 9 POLYGON ((500071.5 5000085,... 9
#> 10 POLYGON ((500044.6 5000033,... 10
res$index # cell_id assignment for each input point
#> [1] 5 6 9 15 2 13 14 11 8 1 3 4 10 7 12