The rules the package applies to the spatial layers it is given: how two layers are brought into one CRS, how a layer without a CRS is read, how mixed dimensions and rows without a location are handled, what a boundary needs, and what s2 refuses in longitude and latitude. A function's own page says how it applies them: which of its arguments they cover, and whether a row it leaves out is reported by a warning or in the log.
Coordinate reference systems
A function that takes two layers, such as points and a boundary or
features and cells, brings them into one CRS before it reads either.
harmonize_crs() is the rule in its plain form: when both layers have a
CRS, one is transformed into the other's; a layer without one is read by
the test in "Layers without a CRS" and then reprojected or stamped, with
a warning.
A function that measures distances moves a lon/lat layer into the
projected CRS ensure_projected() chooses from the layer's extent: the
UTM zone for a local extent, otherwise the candidate that distorts
distances least (its page gives the cases). A layer that already has a
projected CRS is used as it is. Distances, and arguments given as
distances, are in the units of the CRS the function works in, which its
page names. For a lon/lat layer the function projects, that is the CRS
ensure_projected() chose, whose unit is the metre.
Layers without a CRS
A layer without a CRS is read by a test of its coordinates. When their
bounding box lies within longitude -180 to 180 and latitude -90 to 90,
and they either span more than one unit on some axis or carry the
decimal places of degrees, they are taken as EPSG:4326, with a warning.
Otherwise they are left as they are. A small planar survey inside that
box is read as degrees, so set the CRS of such a layer with
sf::st_crs(x) <- ... before passing it.
Given a CRS to read the layer in (target_crs, or the CRS of a second
layer), coordinates the test takes for degrees are reprojected from
EPSG:4326, and the others are stamped with that CRS and not moved. A
stamp is a relabel: check that the coordinates are in that CRS. A CRS in
longitude and latitude is never stamped on coordinates that cannot be in
it. An x outside -180 to 360, or a y beyond 90 north or south, stops the
call with an error that gives the bounding box of the coordinates.
Mixed dimensions, Z and M
sf reads a layer in the dimension of its first geometry, and GEOS
refuses M. A function that moves a layer into another CRS and returns
it, or reduces it to points, reads a layer that mixes XY and XYZ (or
XYM) geometries, as rbind() of an XY and an XYZ layer gives, in x and
y. It returns that layer in XY, with a warning of class
spatialkit_zm_dropped (its page names any exception). A layer in one
dimension, XYM and XYZM included, is moved with its Z and M, and so is a
layer whose only geometries of another dimension than the first are
empty and not points.
A layer a function only reads for its x and y, such as a boundary or
the points and cover of a builder, is read in x and y when it mixes
dimensions or its geometries carry M (XYM or XYZM). coerce_to_points()
reduces a geometry that carries M in x and y as well, with the same
warning; its page gives the exceptions.
Rows without a location
A row has no location when its geometry is empty, or one of its
coordinates is not finite or lies beyond 1e150. Such a row takes no part
in the choice of a projection, and its coordinates none in the lon/lat
test. Moved into another CRS, it comes back empty, in its own geometry
type. sf::st_transform() alone would drop the vertex it cannot move,
or put a coordinate beyond 1e150 at a finite place, and return the rest
of the feature.
In a geographic CRS a vertex at a latitude beyond 90 is no place on the
Earth. A row with one takes no part in the choice of a projection either.
coerce_to_points(), prep_model_data() and the fits, the points of the
k-means seeders, the features of assign_features_to_polygons(), the
pooled columns of summarize_by_cell() and cell_values_at(), and
ensure_stable_poly_id() read such a row as a row without a location.
coerce_to_points() and ensure_stable_poly_id() say so with a warning
of class spatialkit_lat_beyond_90 that names the rows.
A row that has a location and that the target CRS cannot place in full
comes back empty, or without the vertices that CRS cannot place, with a
warning of class spatialkit_rows_unplaced that names the rows.
What a function does with such a row (drops it, keeps it with NA, or
leaves it out of one step) is on its page.
Boundaries
A boundary is a polygonal sf or sfc layer: the study area that cells are clipped to, that seeds are drawn in, or that fold blocks are cut from.
When exactly one of the data layer and the boundary has a CRS, the other is read in it, with a warning. A boundary without a CRS given with lon/lat points is read as lon/lat when its coordinates fit longitude and latitude, and refused with an error otherwise.
A row that is empty, or has a coordinate that is not finite or lies beyond 1e150, read as given and again after any move into another CRS, covers no ground and is left out. A boundary with no such row left is refused with an error that says so.
A boundary in a geographic CRS with a vertex at a latitude beyond 90 is refused with an error of class
spatialkit_cells_degeneratethat names its rows and says to check its CRS.A row the repair of the boundary leaves without a polygon (a ring with no height: every vertex on one line, or in degrees on one parallel) is left out as well, and a boundary with no polygon left is refused.
A boundary that mixes dimensions or carries M is read in x and y.
get_voronoi_seeds() adds the rules for drawing points inside a
boundary, and make_folds() the rule for a block the boundary only
touches.
Polygons in degrees
With s2 on (sf::sf_use_s2(), sf's default), sf reads polygons in
longitude and latitude on the sphere, and s2 refuses a polygon that is
not valid there: one whose edges cross, or with two corners it reads as
one point. Cells returned in lon/lat can hold two such corners. This
happens where four Voronoi seeds stand the same distance from one point,
and the transform to degrees puts two corners that differ only by
rounding at one point (see crs in create_voronoi_polygons()).
A function that joins, measures or unions such a polygon in degrees
stops with an error that names its rows, quotes s2's reason and says to
transform the layer to a projected CRS, such as the one
ensure_projected() picks for it. The class is
spatialkit_cells_degenerate for cells and boundaries, and
spatialkit_features_degenerate for features being assigned or reduced
to points. Some steps repair the polygons first, such as the
largest-overlap join of assign_features_to_polygons() and the union of
a boundary in get_voronoi_seeds(), and stop only when s2 refuses a
repaired polygon.
A hex or square grid built with a geographic crs is laid in degrees
(create_grid_polygons()). Voronoi cells asked for in a geographic crs
are built in a projected CRS and then transformed.
Coordinates far from the origin
Far from the origin of a CRS, doubles are spaced more widely: 0.125 apart
at 1e15. Where they are spaced more than a millionth of a layer's extent
apart, edges and points are held to that spacing, and a point within it
of an edge can fall on the other side. The functions that build cells,
blocks and joins still run, with a warning of class
spatialkit_xy_imprecise that gives the spacing and the extent;
clip_target_for() stops with an error of class
spatialkit_xy_imprecise_error where its buffer comes back empty or
with no area. Those that search for neighbours (estimate_sac_range(),
fit_gwr_model(), residual_morans_i()) give the same warning where a
distance lies past a tie by less than the rounding. Subtract a constant
from the coordinates to bring them nearer the origin.
See also
spatialkit-conditions for every condition class named here,
ensure_projected() for the choice of a projected CRS, and
harmonize_crs() for aligning two layers.
Other data preparation:
[.spatialkit_rows(),
coerce_to_points(),
ensure_projected(),
harmonize_crs(),
prep_model_data()