Picks the level a criterion prefers, together with the flat region:
every level whose criterion value is within tol of the optimum.
Report the flat region with the count.
On the default profile, one size scored for pooled values, the default
criterion is that size: it returns the count the size gives, with no
optimum and no flat region (see "A profile built with an estimate"); what
follows is about the criteria read on a ladder of counts. When the
optimum sits at an end of the levels the criterion was scored at,
the result says so and names the bound, because a bound is then doing the
choosing rather than the criterion (see
resolution_profile for what each criterion measures and
what it returns in practice). The functions that take the result as a
cell count raise that as a warning of class
spatialkit_bound_chosen.
Usage
select_resolution(
profile,
criterion = c("auto", "cp", "reliability", "elbow", "moran_z", "loo", "size"),
tol = 0.02,
range_floor = TRUE,
diagnostic = FALSE,
obs_per_cell = NULL
)Arguments
- profile
A
resolution_profile.- criterion
Which rule sets the count:
"cp"(minimised),"reliability"(maximised at or above the range floor),"elbow"(maximised),"loo"(the leave-one-out error of the profile's estimate, minimised),"size"(the countobs_per_cellgives),"auto"("size"for a profile of pooled values,"loo"for one of plain means,"cp"for a profile without an estimate) or, withdiagnostic = TRUE,"moran_z"(\(|z|\) minimised). Default"auto".- tol
Width of the flat region. For
cp,reliabilityandlooit is relative to the optimum's value (0.02keeps levels within 2 percent of it); forelbowandmoran_z, whose optimum can be zero, it is relative to the criterion's range over the ladder. Under"size"there is no flat region, andtolis the margin by which the cells have to beat one mean forstructuredand nothing else.- range_floor
For
criterion = "reliability"only.TRUE(default) reads the criterion at the levels at or above the range floor inattr(profile, "bounds"). It applies when the layer supports the floor, some scored level reaches it, and the profile built its own ladder (a ladder set withlevelsis read as given).FALSEreads every level.- diagnostic
criterion = "moran_z"is refused, with an error of classspatialkit_diagnostic_criterionthat says what the column measures, unless this isTRUE:moran_zis a diagnostic of the cell means, not a count rule. DefaultFALSE.- obs_per_cell
For
criterion = "size": the mean number of rows per cell wanted, a single number of at least 1 (fractions are allowed).NULL(default) is the profile's own size when it was built at exactly one (resolution_profile(obs_per_cell = )), and 4.5 otherwise. Given with a criterion that is not"size"it is an error.
Value
A list of class resolution_selection with these elements:
bestThe level.
flatThe levels in the flat region, ascending: a set, which can skip a rung.
criterionThe criterion applied, never
"auto".valueThe optimum.
at_ceiling,at_floorWhether the optimum is the last or first of the levels this criterion was read at, which for
moran_zstarts above nine cells and forreliabilityat the range floor; bothNAunder"size", which searches for no optimum.edgeWhich bound that is, in words: the support ceiling, the subsample's ceiling, the range floor, the ladder's own end, the finest or the coarsest size offered on a ladder
obs_per_cellset, the only level scored, or the first or last level the criterion is computable at;NAfor an interior optimum and under"size".n_levelsThe levels on the profile.
valuesThe criterion at every level,
NAwhere it could not be computed.structuredFor
cp:FALSEwhencpat one cell is not above the optimum by more thantol(below it included), when the cell means at the optimum differ from one mean by no more than chance allows, or when the variogram found no spatial structure;TRUEwhen the optimum beats one cell on both counts (see "What each criterion returns"). Forlooandsizeon a profile built withestimate:FALSEwhen the leave-one-out error of one mean for all scored rows is withintolof the error atbest, or below it, or when the cell means atbestdiffer from one mean by no more than chance allows;TRUEwhen the cells beat one mean on both counts.TRUEfor anelbow;NAforreliabilityandmoran_z, and for a profile that carries no one-cell value.one_cellcpat one cell undercp; the leave-one-out error of one mean for all scored rows underlooandsize;NAotherwise.structure_pThe p-value of the F test of the cells at
bestagainst one mean, multiplied by the number of levels searched and capped at 1 (a size searches one level);NAwherestructuredis not read offcpor the leave-one-out error.range_floorThe floor
reliabilitywas held to, orNA.noteWhat the flags mean, in words: a character vector, one note an element;
NULLwhen there is nothing to say. The notes written under"loo"and"size", and for a profile built withestimateor with one size, carry names:size(the size that set the count),held(a size the profile held to the most cells k-means can place),structure(why the count is not identified),finest(the lowest error of pooled values is at the finest level scored),estimate(cpscores plain means, on a profile of pooled values) andladder(the ladder is one size). A note ofcpormoran_zabout the criterion itself has no name. The warning of classspatialkit_no_structurethat the functions taking the selection as a count raise carries every note but those namedsize,held,finest,estimateandladder.seedsAn sf POINT layer, with
seed_id, of the centres of the partition the profile scored atbest, in the CRS it was computed in;NULLfor a profile that does not carry them. See "Seeds" below.partitionFor a profile built with
partition = "density"orinit = "random":kind,init,density_poweranddensity_k. The seeds carry it asattr(, "partition"); the cells are those the profile built, whatever kind built them. It stays the last element.
For "loo" and "size", and for any criterion on a profile
built with estimate, the list has these elements after
seeds:
estimateThe profile's,
"mean"or"pooled";NAfor a profile without one.obs_per_cellRows per cell at
best: the rows a size divides overbest;NAfor an object that keeps no row count.obs_per_cell_askedThe size asked for;
NAunless the criterion is"size".scored_per_cellThe profile's column at
best: the rows the leave-one-out error read over the cells that hold one. It is notobs_per_cell: it leaves out rows the error did not read and cells that hold none of them, as underselect_on = "split".loo,loo_one_cellThe leave-one-out error at
bestand that of one mean for all scored rows.share_alone,own_weightThe profile's columns at
best.count_ruleA list of class
spatialkit_count_rulethat records how the count was set:rule(the criterion applied),estimate(the estimate the rule was computed for: the profile's for"size"and"loo","mean"for"cp",NAotherwise),cells,obs_per_cell,obs_per_cell_asked,response,n(the rows the size divides),n_points,n_fit(the rows the centres were fitted to; fewer thann_pointsfor a subsample),seed,features,scored(what the profile scored atbestfor its estimate:estimate,n,cells,loo,loo_se,loo_one_cell,share_alone,own_weight,structured,rowsandcentres, the matrix of the centres the rows were scored in, incrsand in the profile's order;NULLwithout an estimate),partition,crsandscored_cells(NA: the record stands for a count).
A "cp" selection off a profile without an estimate has
count_rule as well, after seeds, and nothing else of
this list: its estimate is "mean", since \(C_p\) scores
plain means, and scored is NULL. Under "loo" and
"size" one_cell holds the leave-one-out error of one mean
and range_floor is NA.
seeds carries the same record as attr(, "count_rule")
with scored_cells = TRUE, since they are the centres that were
scored, or FALSE when they were refitted to every point, since
they are then other cells built from the count. The record travels on
with the seeds, the cells and the assigned layer to
summarize_by_cell(), which warns when it reports another
cell value than the count was chosen for (class
spatialkit_estimate_mismatch) and when the cells or rows it is
given are not the ones the count was scored on
(spatialkit_cells_differ).
Seeds: the Voronoi cells of the seeds are the cells that were scored;
get_voronoi_seeds(method = "kmeans", n = <this>) and
voronoi_seeds_kmeans(k = <this>) return them. On a
profile without an estimate whose centres were fitted to a subsample
(n_sample below n in attr(profile, "bounds")) the
seeds are those centres refitted to every point: the kind's own
iteration (Hartigan and Wong's for "kmeans", Lloyd's on every
point's density weights for "density") run from the centres
scored, with the profile's iteration limit and no random draw. Where
Hartigan and Wong's algorithm refuses the centres, Lloyd's iteration
with every weight one runs in its place, and a log line says so. Such
seeds carry attr(, "refit"): rows (the points),
subsample (the points the profile fitted to), kind,
iter, iter_max, converged, wss_scored (the
within-cell sum of squares of every point in the cells of the centres
scored, each cell about its own mean) and wss (the same of the
refitted cells). Their cells are then not the cells scored, and the
count is still the one the subsample gave; the centres scored are
attr(profile, "centres")[[as.character(best)]]. The refit reads
every point's coordinates from attr(profile, "refit_rows"); on a
profile without that attribute the centres scored are the seeds, and a
log line says so. The refit is not run either, and the centres scored
are the seeds, when it would pass the work limits of a profile's own
fits (see "Conditions" in resolution_profile); a log line
says so. A profile with an estimate scores it on every row of the
layer in the cells of the centres fitted to the subsample, so its seeds
are those centres, whose cells are the cells scored. summary()
and plot() of a profile read no seeds and refit nothing.
What each criterion returns
cpThe level that minimises Mallows' \(C_p\): the count at which re-measuring the sampled sites, each predicted by its cell's mean, has the least estimated error (
resolution_profilesays what that leaves out for a new location). On a smooth response with little noise that is the support ceiling. The result also says whether the optimum beats one cell for the whole layer (attr(profile, "one_cell")), instructured. It isTRUEwhen two things hold: \(C_p\) at one cell is above the optimum by more thantol, and the cell means at the optimum differ from one mean by more than chance allows. The second is the F test of the cells against one mean, \((TSS - RSS) / (L - 1)\) over \(RSS / (m - L)\), at 5 percent after a Bonferroni adjustment for the levels the optimum was searched over (structure_pis the adjusted p-value). The cells are fitted to the coordinates alone, so the test holds its level on a response with no spatial structure whatever \(C_p\)'s noise variance is, and it is what decides when that variance is 0: \(C_p\) is then \(RSS / n\), which falls with every finer level by chance alone, and the first comparison says nothing. When either fails,structuredisFALSE: one mean for the whole layer predicts as well as any level scored, so the response shows no spatial structure the cells can use and the count is not identified.structuredis alsoFALSEwhen the profile's variogram was refused for showing no spatial structure.bestis still the argmin. The F distribution is exact for a Gaussian response. The test has little power on a small layer, so aFALSEthere is weak evidence that there is no structure.reliabilityThe level of highest reliability at or above the range floor the profile reports (when the layer supports the floor and the profile built its own ladder). The reliability curve often peaks below the floor, and the floor is a level of every such ladder, so the result is often the floor, the coarsest count the range allows, with
edgenaming it (on a profile whose k-means failed at that level, the first level above it).range_floor = FALSEreads every level and returns the curve's own maximum, which can be a count below the floor.elbowThe number of clusters of the points, when they cluster; an error otherwise, because the column is
NAat every level unless the WSS curve bends.moran_zRefused unless
diagnostic = TRUE. It is the level at which neighbouring cell means (or, with predictors, their regression residuals) are least autocorrelated. \(|z|\) is near 0 at 10 to 20 cells whatever the data and grows as cells get finer than the range, so its minimum is usually the first level it can be computed at, or one near it, and it says nothing about how well the cells represent the response.looThe level with the lowest leave-one-out error of the estimate the profile was built for (
resolution_profile(estimate = )); of levels with the same error, the one with the fewest cells. The flat region is every level whose error is withintolof the lowest. The column needs no variogram.structuredis read as forcp, with the leave-one-out error in place of \(C_p\): it isTRUEwhen the error of one mean for all scored rows is above the optimum by more thantoland the F test of the cells at the optimum against one mean, adjusted for the levels searched, has \(p < 0.05\);one_cellthen holds the error of one mean. Under this criterion the count depends on the values of the response. When the profile's estimate is the pooled value and the lowest error is at the finest level scored, a note says that the end of the ladder chose the count. For pooled values the error tends to keep falling to the finest level (see "How this was checked" inresolution_profile). On a ladderobs_per_cellset, an optimum at an end has theedge"the finest size offered (obs_per_cell)"or"the coarsest size offered (obs_per_cell)"; a finest level the profile held to the most cells k-means can place keeps the label of the support ceiling.sizeThe count a size gives,
max(2, round(n / obs_per_cell)), withnthe rows the size divides: the rows with a response, or every point for a profile without one. No optimum is searched for. The level returned is the first of three that applies: the level the profile built for that size; the count itself, when the profile has a partition at it; otherwise the built level nearest to the count on the log scale (of two as near, the one with fewer cells), with a warning of classspatialkit_size_not_reached, which says so when the count is more than k-means can place on the layer. It reads any profile, one built without a response or without an estimate included, but not a column subset, which has lost the row count.flatis the level,valuethe rows per cell it leaves (n / best), andat_ceiling,at_floorandedgeareNA: no bound chose anything, so the functions that take the selection as a count raise nospatialkit_bound_chosen. Under this rule neither the cells, which are fitted to the coordinates, nor their number, which is a count of rows, depend on the values of the response. A size does not ask whether the response has structure the cells can use, sostructuredasks it separately, on a profile built with anestimate. It isFALSEwhen the leave-one-out error of one mean for all scored rows is withintolof the error at the level, or below it, or when the F test of the cells at the level against one mean has \(p \ge 0.05\). The count stands either way, since a size set it and no criterion:structured = FALSEsays that the cell values will say little that one mean for the layer does not. The functions that take the selection as a count then raisespatialkit_no_structure. On a profile without an estimatestructuredisNA.autoThe rule that goes with the profile's estimate:
"size"for a profile built withestimate = "pooled","loo"forestimate = "mean", and"cp"for a profile without an estimate. A column subset of a profile has lost the record of its estimate and is read by"cp".criterionin the result is the criterion applied, never"auto".
A profile built with an estimate
This function's default criterion is "auto": "size" for a
profile of pooled values, "loo" for one of plain means and
"cp" for a profile without an estimate. A profile built with
estimate that is passed straight to
get_voronoi_seeds(), voronoi_seeds_kmeans() or
build_tessellation() as the count is read the same way, so
select_resolution(profile) and the profile itself give the same
count. A profile of pooled values built with a ladder argument
(n_levels and the others) is read by the size as well: the
default returns the level nearest the count the size gives, on the
automatic ladder its top level, with spatialkit_size_not_reached.
criterion = "cp" reads \(C_p\) on a profile that has it.
cp is computed on such a profile as on any other and scores plain
means; when the profile's estimate is the pooled value the
result's note says so.
"cp" and "reliability" cannot be read off a profile whose
ladder obs_per_cell set under sac = "auto". Such a profile
fits no variogram, both columns are NA at every level, and the
call is an error that names the ways to get them: build the profile with
sac = NULL, with a sac of your own, or with
obs_per_cell = NULL. The default profile is such a profile. On a
ladder of one size that has a
variogram either criterion returns the one level, with edge
"the only level scored".
For a ladder of one size, summary() of the profile lists each
criterion that is finite at the level and says that the size set the
count, and plot() draws each as one point, with no selected level
and no flat region. When none is finite, as on a constant response, where
loo is NA too, or when no row of the selection half has a
response (select_on = "split"), summary() stops with an
error that says so. In that last case "cp" and "moran_z",
and "loo" with an estimate, are errors that give the same
reason, except "cp" on a size ladder that fitted no variogram,
which gives the size ladder's reason, as above.
Examples
library(sf)
# An exponential field with range parameter 200 (true effective range
# 600 m) on a 1 km square, with a nugget of 0.6 on a unit sill.
set.seed(4)
n <- 400
xy <- data.frame(x = 5e5 + runif(n, 0, 1000), y = 5e6 + runif(n, 0, 1000))
D <- as.matrix(dist(xy))
xy$z <- as.numeric(t(chol(exp(-D / 200) + diag(0.6, n))) %*% rnorm(n))
pts <- st_as_sf(xy, coords = c("x", "y"), crs = 32632)
# The default profile is one size scored for pooled values, and the
# default criterion, "auto", reads it by that size.
select_resolution(resolution_profile(pts, response_var = "z"))
#> Resolution by size: 89 cells
#> size : 4.5 rows per cell, the default (obs_per_cell); 400 rows / 89 cells = 4.49
#> cells : density-weighted k-means++ starts (power 1, 8 neighbours)
#> estimate : pooled toward the 8 nearest cells
#> at this size: 1.0% of the rows are alone in their cell; median own weight 0.40
#> loo : 0.903 (one cell for the layer: 1.23)
#> note : the count is set by obs_per_cell = 4.5, the default; no
#> criterion chose it.
# A ladder of counts for plain means, read by Mallows' Cp.
prof <- resolution_profile(pts, response_var = "z", n_levels = 12,
estimate = NULL)
sel <- select_resolution(prof, criterion = "cp")
sel # the level, and the flat region around it
#> Resolution by cp: 19 cells
#> flat region : 19 to 25, 44 (3 of 12 levels)
#> cells : density-weighted k-means++ starts (power 1, 8 neighbours)
sel$flat # every level within `tol` of the optimum
#> [1] 19 25 44
sel$edge # the bound the optimum sits on; NA when interior
#> [1] NA
sel$structured # FALSE when one cell for the layer does as well
#> [1] TRUE
# Reliability prefers coarse cells: it is read at or above the floor the
# autocorrelation range sets, and the result says in words when the
# floor is choosing.
rel <- select_resolution(prof, criterion = "reliability")
rel
#> Resolution by reliability: 4 cells
#> flat region : 4 to 6 (3 of 12 levels)
#> cells : density-weighted k-means++ starts (power 1, 8 neighbours)
#> note : the optimum is the range floor (area / range^2); the bound is
#> choosing, not the criterion. Fewer cells would be wider than
#> the range and average over more than one patch of the field.
rel$at_floor
#> [1] TRUE
rel$edge
#> [1] "the range floor (area / range^2)"