Every condition class the package raises, with the functions that raise it, what it means, what to do and the fields it carries. Each class can be caught by name.
Catching a condition by class
Each condition below is an R warning or error whose class vector starts
with the class named, followed by "warning" or "error" and
"condition". A handler named after the class catches it without
matching the message, and reads its fields with $:
w <- tryCatch(determine_optimal_levels(pts),
spatialkit_no_elbow = function(w) w)
w$kwithCallingHandlers() with invokeRestart("muffleWarning"), or
suppressWarnings(expr, classes = ), lets the call finish and drops the
warning. options(warn = 2) turns every warning into an error.
Some warnings and errors carry no class of the package's own, such as
the refusal of an argument of the wrong type. Catch those with
warning = or error =.
Warnings and log lines
The package also writes a log through logger: a trace in a
temporary file, and a console echo of every line at the WARN level and
above. A log line is not an R condition. tryCatch(warning = ) does not
catch it, and suppressWarnings() does not silence it. Where a help page
says a function raises a warning, it means an R warning; where it says
the function logs one, it means a log line. spatialkit_quiet() turns
the console echo off.
The package writes a classed warning to the log as well as raising it, so a warning muffled by a handler still prints its log line until the echo is turned off.
Condition classes
Each entry gives the class, the functions that raise it, what it means
and what to do, and then the fields a handler reads with $. Each is a
warning unless marked as an error. An entry without fields is a
condition that carries only its message.
spatialkit_aoa_zero_threshold. Raised byarea_of_applicability()withfolds. The dissimilarity threshold is 0: held-out rows have exact copies on the training side of their fold. Use folds that keep copies together, such asmake_folds(method = "leave_location_out", group_var = ).spatialkit_bound_chosen. Raised byget_voronoi_seeds(),voronoi_seeds_kmeans()andbuild_tessellation(), given a profile or a selection as the count. The optimum sits on a bound of the ladder, so a bound of the ladder set the count. Readedgein theselect_resolution()result;resolution_profile()describes the bounds. Fields:edge,criterionandn.spatialkit_cells_degenerate(error; a warning fromensure_stable_poly_id()). Raised bybuild_tessellation(),create_voronoi_polygons(),create_grid_polygons(),clip_target_for(),get_voronoi_seeds(),voronoi_seeds_random(),make_folds(),assign_features_to_polygons(),summarize_by_cell(),cell_values_at()andensure_stable_poly_id(). s2 refuses a cell or a boundary row in lon/lat even after repair, or a boundary in a geographic CRS has a vertex beyond latitude 90. Fromensure_stable_poly_id(): the repair left a row with no polygon. Transform the layer to a projected CRS; for a latitude beyond 90, check its CRS. Fields:rows,nandreasons; the error also carriesparent,repairedands2_forced, and some steps addsite,causeorfeatures_rows.spatialkit_cells_differ. Raised bysummarize_by_cell(). The rows or cells given are not those the count was scored on;whatsays which check differs. Summarise the layer the count was chosen on, assigned to the cells built from that selection. Fields:what,scoredandfound, andfieldfor the count record.spatialkit_constant_predictor. Raised byprep_model_data(), and so by every fitter andcv_*()function. A predictor takes one value in every row kept, so its coefficient cannot be told from the intercept. Drop it frompredictor_vars.spatialkit_constant_response. Raised byresolution_profile(). The scored variable is constant to within rounding, socp,moran_iandmoran_zareNAat every level. Check the response. Withpredictor_vars, a response the predictors fit exactly leaves constant residuals. Fields:n.spatialkit_convergence. Raised byfit_bayesian_spatial_model(),cv_bayes()andcv_spatial(). The sampler's diagnostics fail (divergent transitions, R-hat, effective sample size or E-BFMI), andconvergence_okisFALSE. Raiseadapt_deltafor divergent transitions; run more iterations for R-hat and effective sample size. Fields:failed, and from cross-validation alsofoldsandfold_messages.spatialkit_cp_noise. Raised byresolution_profile().cpdoes not take the variogram's nugget as it stands, or has no noise variance and isNAat every level. Readattr(, "cp_noise")for the variancecpused and its source. Fields:source,value,level,cap,uncapped_sourceanduncapped_value.spatialkit_deff_fallback. Raised bysummarize_by_cell(). The design effect requested was not the one applied: a"variogram"request fell back to Kish's, or a number given was refused. Read thedeff_methodcolumn;deff_method == "variogram"keeps the rows the variogram corrected. Fields, for a"variogram"request:requestedandused.spatialkit_deff_no_structure. Raised bysummarize_by_cell(). The variogram of the response found no spatial structure, so the predictor columns named get a design effect of 1 from a verdict about the response. Usedeff = "kish"to give each predictor its own ICC. Fields:columnsandreason.spatialkit_diagnostic_criterion(error). Raised byselect_resolution().criterion = "moran_z"was asked for withoutdiagnostic = TRUE.moran_zis a diagnostic of the cell means, whichselect_resolution()reads only underdiagnostic = TRUE. Passdiagnostic = TRUE, or choose another criterion.spatialkit_diagnostic_ranking. Raised bydetermine_optimal_levels()withcriterion = "morans_i". The candidates are ranked by Moran's z of the cell means, a diagnostic of the cells. Usecriterion = "geometric", orresolution_profile()when the response should drive the count. Fields:k,criterion,first_computableandwindow.spatialkit_empty_cells. Raised byresolution_profile(),get_voronoi_seeds()andvoronoi_seeds_kmeans()withpartition = "density". A centre holds no point, so fewer cells are occupied than the count. It happens at high counts, mostly from random starts. k-means++ starts (init = "kmeans++") leave a cell empty less often. Fields:levelandempty.spatialkit_estimate_mismatch. Raised bysummarize_by_cell(). The summary reports another cell value than the count was chosen for: plain means against pooled values, or the reverse. Report the value the count was chosen for, or choose the count for the value you report. Fields:chosen_for,reported,ruleandcells.spatialkit_features_degenerate(error). Raised bycoerce_to_points(),prep_model_data(),assign_features_to_polygons()andcell_values_at(). s2 refuses a polygon of the features in lon/lat, GEOS puts the centroid of an invalid feature outside it, or a temporary projection leaves a line empty. Transform the features to a projected CRS, choose anothermodeincoerce_to_points(), or repair them withsf::st_make_valid(). Fields:rows,n,reasons,parent,repairedands2_forced, and some steps addsite,crsorauto_helps.spatialkit_few_residuals. Raised bysummarize_by_cell()withobs_level. Fewer than five residuals are expected beyond each end of the interval (at 0.90, fewer than 100 residuals), so its ends are unstable. Ask for a lowerobs_level, which needs fewer residuals. Fields:columns,needed,levelandn.spatialkit_fold_args_ignored. Raised bycv_spatial(),cv_rf(),cv_gwr(),cv_bayes()andcompare_models_cv().block_sizeorauto_range = TRUEwas given besidefolds, which leaves them nothing to size. Drop them, or leave outfoldsso the function builds the blocks.spatialkit_gp_adequacy. Raised byfit_bayesian_spatial_model(),cv_bayes()andcv_spatial(). The basis of the Bayesian GP is too coarse: the posterior asks for a shorter length-scale than it resolves, or the residuals are autocorrelated at short range. Follow the message: a finer basis (gp_k,gp_resolution) or, at its cap, kriging or a model of cell means. Fields, from cross-validation:foldsandfold_messages.spatialkit_gp_basis_size. Raised byfit_bayesian_spatial_model(),cv_bayes()andcv_spatial(). Fewer than one row per ten basis functions, so most basis weights are set by their prior. A smallergp_kis cheaper and resolves less; with this few rows kriging fits the same kind of model. Fields, from cross-validation:foldsandfold_messages.spatialkit_gp_resolution. Raised byfit_bayesian_spatial_model(),cv_bayes()andcv_spatial(). A variogram fitted before compiling puts the response's range below what the basis resolves, and the response's autocorrelation agrees. The check after sampling tests this estimate. The message gives the basis size that would resolve the range. Fields, from cross-validation:foldsandfold_messages.spatialkit_gwr_extrapolation. Raised bypredict.gwr_fit(),predict_surface(),cv_gwr(),cv_spatial(),cv_block_size_sweep()andselect_features_forward(). New locations lie beyond the reach of the widest kernel; they are predicted and counted. Where extrapolation is intended, usesuppressWarnings(expr, classes = "spatialkit_gwr_extrapolation"). Fields:n_far,n,reach,reach_text,nearestandcalls.spatialkit_gwr_not_estimable. Raised bypredict.gwr_fit(),predict_surface(),cv_gwr(),cv_spatial(),cv_block_size_sweep()andselect_features_forward(). The local regression at a new location cannot be estimated, so its prediction isNA.predict.gwr_fit()says when a window cannot be estimated. Fields:n_na,n,n_empty,bw_textandcalls.spatialkit_gwr_rank_deficient. Raised byfit_gwr_model(). Some local windows have deficient rank, and their coefficients areNA; the fitted values are returned. Where many windows hold a predictor constant, fit it as one global coefficient (a mixed GWR, asGWmodel::gwr.mixed()fits).spatialkit_gwr_repeated_locations. Raised byfit_gwr_model()andgwr_model_selection(). Rows share coordinates. AICc counts them as independent, so a bandwidth left to the search (bandwidth = NULL) is chosen by leave-one-location-out error, and the AICc gaps between models make what a predictor adds look larger than it is. Read "Observations that share a location" infit_gwr_model().spatialkit_icc_unavailable. Raised bysummarize_by_cell(). A column's Kish ICC cannot be estimated, so its standard errors and intervals areNAin cells of two or more observations.attr(, "icc")$reasonsays why. Fields:columnsandreason.spatialkit_k_reduced. Raised bymake_folds(), and the functions that build folds with it. Fewer folds were made than asked for. Readkin the result; the message gives the reason and a setting that works. Fields:k_requestedandk.spatialkit_knndm_short_of_target. Raised bymake_folds()withmethod = "knndm". The held-out points sit closer to their training data than the prediction points do, so the cross-validated error tends to read low. Use fewer folds; each then holds out a larger part of the layer. Fields:held_out_meanandtarget_mean.spatialkit_ladder_unused. Raised byresolution_profile(). A numericobs_per_cellsets the ladder, so then_levels,min_cell_n,sample_norrange_floor = TRUEalso given are not read. Passobs_per_cellor those arguments, not both. Fields:unusedandobs_per_cell.spatialkit_lat_beyond_90. Raised bycoerce_to_points()andensure_stable_poly_id(). Rows of a layer in a geographic CRS have a vertex at a latitude beyond 90, which is no place on the Earth.coerce_to_points()gives them an empty point;ensure_stable_poly_id()keys them as empty polygons and returns them as they came. Check the layer's CRS and the order of its coordinates. Fields:rowsandn.spatialkit_moran_skipped. Raised byresolution_profile(). A level has more than 5,000 cells holding a scored row while FNN cannot be loaded or Matrix is not installed, somoran_iandmoran_zareNAthere. Install Matrix, or reinstall FNN. Fields:limit,levelsandmissing.spatialkit_new_levels. Raised bypredict.bayesian_fit(). Rows carry a level of a categorical predictor that the model was not fitted with, so their predictions areNA. The warning names the predictor, the levels and the number of rows.spatialkit_nndm_out_of_reach. Raised bymake_folds()withmethod = "nndm"or"knndm". The prediction points sit nearer to the data than any fold can hold a point out, so the cross-validated error is pessimistic for them. No fold setting closes the gap; read the score as an upper bound on the error at those points. Fields:deficit,toleranceandseparated.spatialkit_no_cover. Raised bybuild_tessellation()andcreate_voronoi_polygons(). Seeds came with neither a boundary nor a cover, so their cells cover only the seeds' own hull. Pass the study area asboundary, or the observations ascover.spatialkit_no_default_criterion(error). Raised byget_voronoi_seeds(),voronoi_seeds_kmeans()andbuild_tessellation(). A profile passed as the count hascp, the criterion a profile is read by,NAat every level while another criterion is finite. Passselect_resolution(profile, criterion = )with a finite criterion, or a number.spatialkit_no_elbow(an error underon_no_elbow = "error"). Raised bydetermine_optimal_levels(). The WSS curve has no elbow, or the ladder is too short to show one, so the count it gives is set by the ladder. Choose the count on other grounds, such asresolution_profile()with a response. Fields:k,sagandstructured.spatialkit_no_scored_rows. Raised byresolution_profile(). No row of the selection half has a response (select_on = "split"), or no row has a response and every predictor, so the columns that read those rows areNAat every level.reasonsays which; check where the rows with a response and every predictor lie. Fields:reason,n,selection,n_responseandcolumn.spatialkit_no_structure. Raised byget_voronoi_seeds(),voronoi_seeds_kmeans(),build_tessellation()andsummarize_by_cell()withestimate = "pooled". One cell for the whole layer does as well (structuredisFALSE), so the cell values say little that one mean does not. The call goes on with the count. The message says which test failed, and whether a size set the count; see "Pooled values" insummarize_by_cell(). Fields:criterion,nandone_cell, and fromsummarize_by_cell()alsocolumns,estimate,loo,structure_pandbeats.spatialkit_nonfinite. Raised bysummarize_by_cell().Infor-Infin a response or predictor column is treated as missing in every statistic of that column;nstill counts the row. The warning names the columns and gives the rows and cells affected. Fields:nandcolumns.spatialkit_not_converged. Raised byresolution_profile(),get_voronoi_seeds()andvoronoi_seeds_kmeans(). The start kept was cut off at the iteration limit, so a longer run could still move points between cells. Raiseiter_max(kmeans_iteringet_voronoi_seeds()). Fields:level,iteranditer_max.spatialkit_not_supported. Raised byresolution_profile().supportedisFALSE: the range floor exceeds the ceiling, fewer than two cells meetmin_cell_n, or the points sit on one location.attr(x, "bounds")gives the floor, the ceiling andceiling_from. Fields:reason,nandmin_cell_n, andobs_per_cellfor a ladder of sizes.spatialkit_partition_unused. Raised byget_voronoi_seeds()andvoronoi_seeds_kmeans(). Given a profile or a selection, the call also named apartition,initor density setting other than the profile's; the scored centres are returned. Pass the count as a number (n = sel$best) for a fresh k-means. Fields:kindandinit.spatialkit_pool_degenerate. Raised bysummarize_by_cell()withestimate = "pooled". The pooled values carry no pooling: one cell, no spread inside any cell, or no signal between cells.reasonsays which case applies. Fields:reasonandcolumns, withn,constantorsigma2by case.spatialkit_pool_few_cells. Raised bysummarize_by_cell()withestimate = "pooled". The column has 2 to 9 cells, so each target is the mean of all the other cells, and a pooled value can land on the far side of the overall mean from its plain mean. With 10 cells or more each target is the mean of the observations in the 8 nearest cells. Fields:columns,cellsandown_weight.spatialkit_pool_few_df. Raised bysummarize_by_cell()withestimate = "pooled". The spread inside the cells (sigma2), which every own weight rests on, comes from fewer than 30 values beyond one per cell. Fewer cells leave more values beyond one per cell. Fields:columns,needed,df,nandcells.spatialkit_pool_rows_skipped. Raised bysummarize_by_cell()withestimate = "pooled". Rows with a value and a cell have no location; they count innand the plain columns and take no part in the pooled ones. See "Rows without a location" in spatialkit-geometry. Fields:n,cellsandcolumns.spatialkit_pool_unavailable. Raised bysummarize_by_cell()withestimate = "pooled"andresolution_profile()with anestimate. The pooled columns (in a profile,loo,loo_seandown_weight) areNA;reasonsays why. The plain columns are returned. For"values out of range", divide the column by a power of ten; for"work limit", see spatialkit-options. Fields:reasonandcolumns, withnandcells, orwork,limitandcells, by reason.spatialkit_predict_failed. Raised bypredict.bayesian_fit(). The posterior draw failed, and every prediction isNA. The message gives the cause.spatialkit_repeated_locations. Raised bysummarize_by_cell()withobs_levelandresolution_profile()with anestimate. Rows share a location, so the interval orloodescribes a further observation at a place already observed. Fields:n, the rows that share a location, andtotal, the rows read, withcolumnsfromsummarize_by_cell()orcolumnfromresolution_profile().spatialkit_replicate_var_above_nugget. Raised bykriging_adequacy(). The replicates at one location vary between visits more than the variogram's nugget allows; their variance is used as it is. Refit the variogram with a nugget of at least the replicate variance. Fields:within_varandnugget.spatialkit_response_ceiling. Raised byresolution_profile(). Rows that are not scored (no response, or a predictor missing) lowered the ceiling on the count. The message names the bound in force. Fields:n,n_response,ceiling,ceiling_from,n_sampleandn_scored.spatialkit_response_imprecise. Raised byprep_model_data(), and so by every fitter andcv_*()function, and byestimate_sac_range(),kriging_adequacy()andselect_features_forward(). The response lies so far from zero that doubles there are spaced more than a millionth of its standard deviation apart, and every mean is rounded to that spacing. Subtract a constant from the response first. Fields:spacingandspread.spatialkit_response_scale. Raised byfit_bayesian_spatial_model().priorsets a prior on the response's scale, so a response far from zero, or with a standard deviation far from 1, is handed to brms as it is. See "The response's centre and scale" infit_bayesian_spatial_model().spatialkit_rows_dropped. Raised byprep_model_data(), and so by every fitter andcv_*()function, and bygp_lengthscale_bounds(). Rows were dropped for a missing or non-finite value or for having no location. The message gives the counts and how far the dropped rows' mean response sits from the kept rows'. When that difference is large, the fit is biased towards the complete rows. Fields, fromgp_lengthscale_bounds():nandwhich.spatialkit_rows_unplaced. Raised byensure_projected(),harmonize_crs(),plot_tessellation_map(), and the other functions that move a layer into another CRS. The target CRS cannot place a row in full, so the row comes back empty or without those vertices. Correct or drop those rows. Fields:rowsandn.spatialkit_sd_overflow. Raised bysummarize_by_cell(). A cell's standard deviation is beyond the largest double, so its..sd_*isInfand its standard errors and interval areNA. Divide the column by a power of ten. Fields:columnsandcells.spatialkit_size_not_reached. Raised byresolution_profile(),select_resolution()andget_voronoi_seeds(). A size does not give the count it asks for (fewer than two cells, or more than k-means can place), and the nearest level is used. Fields:obs_per_cell,wantedandused, the two counts, andreason.spatialkit_surface_point_off. Raised bycoerce_to_points(). The point GEOS takes on a lon/lat polygon spanning more than 180 degrees of longitude does not lie on it read on the sphere, and that point is kept. Transform the layer to a projected CRS that holds the polygon, and call again. Fields:rows.spatialkit_ties_unresolved. Raised byassign_features_to_polygons(). Thetie_breakrule names no polygon for some features, since the polygons are equal on every key; those features getNA. They are kept or dropped askeep_unassignedsays. Fields:nandtotal.spatialkit_unassigned. Raised byassign_features_to_polygons(),build_tessellation()andcreate_voronoi_polygons(). Features fall inside no polygon, or points or seeds lie outside every cell. Give the cells aboundaryorcoverthat reaches the data;keep_unassigned = TRUEkeeps such features withNA. Fields:nandtotal.spatialkit_variogram_unusable. Raised byresolution_profile(). The variogram gives no usable range, soreliabilityisNA.reasongives therejected_reasonofestimate_sac_range(). Fields:reason,converged,nuggetandnugget_used.spatialkit_work_limit(error). Raised byresolution_profile()andcell_values_at(). A search or a fit would make more comparisons than an option allows. The message says what to change; see spatialkit-options. Fields:work,limitandwhat, and for a fit alsokind,init,nstartandfnn.spatialkit_xy_imprecise. Raised byassign_features_to_polygons(),build_tessellation(),create_voronoi_polygons(),create_grid_polygons(),clip_target_for(),make_folds(),estimate_sac_range(),fit_gwr_model()andresidual_morans_i(). The coordinates lie so far from the origin of their CRS that doubles there are spaced more than a millionth of the extent apart, or a distance lies past a tie by less than that rounding. The call runs on the rounded coordinates. Subtract a constant from the coordinates; see "Coordinates far from the origin" in spatialkit-geometry. Fields:spacing, andextentordistance.spatialkit_xy_imprecise_error(error). Raised byclip_target_for(). At that rounding the buffer comes back empty or with no area. Shift the points nearer the origin, or passboundary.spatialkit_zm_dropped. Raised byensure_projected(),harmonize_crs(),coerce_to_points(),assign_features_to_polygons(),get_voronoi_seeds(),ensure_stable_poly_id(),predict_surface()andarea_of_applicability(). A layer that mixes XY and XYZ (or XYM) geometries came back in XY, orcoerce_to_points()reduced geometries that carry M in x and y. See "Mixed dimensions, Z and M" in spatialkit-geometry. Fields:rows, the rows that carried Z or M.
See also
spatialkit_quiet() for the console log, spatialkit-options
for the work limits, spatialkit-geometry for the rules behind the
geometry classes, and vignette("troubleshooting", package = "spatialkit") for the messages met most often.
Other options and caches:
clear_fitted_cache(),
clear_grid_cache(),
spatialkit-options,
spatialkit_quiet()
Examples
library(sf)
set.seed(1)
# Points spread evenly have no elbow.
pts <- st_as_sf(data.frame(x = 5e5 + runif(200, 0, 100),
y = 5e6 + runif(200, 0, 100)),
coords = c("x", "y"), crs = 32632)
# Catch the warning by its class and read its fields.
w <- tryCatch(determine_optimal_levels(pts, max_levels = 6),
spatialkit_no_elbow = function(w) w)
class(w)
#> [1] "spatialkit_no_elbow" "warning" "condition"
w$k
#> [1] 3
# Let the call finish without the warning; the log line still prints
# until the console echo is off.
old <- spatialkit_quiet()
k <- suppressWarnings(determine_optimal_levels(pts, max_levels = 6),
classes = "spatialkit_no_elbow")
spatialkit_quiet(old)
k
#> [1] NA
#> attr(,"structured")
#> [1] FALSE
#> attr(,"sag")
#> [1] 0